docs: project documentation

- add CONTRIBUTING.md
- add libs and apps readme
- Update docs folder and add outline models and plugins document

CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing
+
+## About the architecture
+
+Most of the code is written using Typescript, the [official Typescript documentation](https://www.typescriptlang.org/docs/home.html) is a good resource to learn about it.
+
+The Flogo Web UI follows a regular client-server model and as such it is divided into two principal components: the server and the client.
+
+The server application (located under [`/apps/server`](/apps/server)) is a NodeJs application. Besides persisting data, the server application wraps the [Flogo CLI](https://github.com/project-flogo/cli) to interact with and underlying Flogo engine project and exposes its functionality to the client application.
+
+The client application (located under [`/apps/client`](/apps/client)) is implemented using the [Angular](https://angular.io/) framework and provides a broswer based UI to design Flogo applications.
+
+Communication between server and client is mostly done through a REST API exposed by the server.
+
+You can find more information in the [application docs](/docs) like an explanation of the
+[directory structure](./libs/). Also there's more information in the README file of the server and client apps.
+
+## Server Environment
+
+Before starting the server copy and rename the [`.env.example`](/.env.example) to `.env`. Add or modify/uncomment
+the environment variables defined in created `.env` file.
+
+You can alternatively set regular environment variables the way your OS supports them.
+
+## Testing
+
+### Before running the tests
+
+Make sure your dependencies are up to date:
+
+```sh
+yarn install
+```
+
+### Running the tests
+
+From the project root:
+
+```sh
+yarn test
+```
+
+This will run the unit test for all the sub packages.
+
+### Running tests for a single subpackage
+
+From the project root:
+
+```sh
+yarn test <name-of-the-package>
+```
+
+For example
+
+```sh
+yarn test parser
+```
+
+## Style guide and code conventions
+
+### Code formatting
+
+Flogo Web uses [Prettier](https://prettier.io/) for code formatting which will automatically format javascript, typescript, css, html and markdown files.
+
+The easiest way to format your code is directly in your code editor, refer to [Prettier's documentation for Editor Integration](https://prettier.io/docs/en/editors.html) for
+an explanation of how to set them up.
+
+Alternatively you can run the `format` script which will format, to all files in the project:
+
+```bash
+yarn format
+```
+
+## Other tasks
+
+All the commands listed in the following subsections are specified as `<command>: description` and they can be run from
+the root of the project as:
+
+```sh
+yarn run <command>
+```
+
+### Managing engine/local data
+
+- `clean:local`: Clean ALL your local data. This will remove the engine, database and logs.
+- `clean:engines`: Remove the local engines only. This will force the server to rebuild the engine on next startup.
+
+### Misc
+
+- `update-global-flogo`: Update global flogo-cli to the latest available
+
+Flogo Web uses npm/yarn scripts for its build process. Take a look at README.md of the packages as well as at the scripts section
+in the `package.json` of the root project and the subpackages to find other commands available.

apps/client/README.md

@@ -0,0 +1,33 @@
+# Flogo Web Client Application
+
+### Style Guides for Reference
+
+Refer to the following style guides if need be:
+
+- [JavaScript Style Guide](https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml)
+- [HTML/CSS Style Guide](https://google-styleguide.googlecode.com/svn/trunk/htmlcssguide.xml)
+- [Angular Style Guide](https://angular.io/guide/styleguide)
+
+## Code conventions
+
+Follow the official [Angular Style Guide](https://angular.io/guide/styleguide).
+
+## Unit and Integration tests
+
+Read [angular's official testing guide](https://angular.io/guide/testing) and about the [different types of testing](https://vsavkin.com/three-ways-to-test-angular-2-components-dcea8e90bd8d).
+
+DO NOT import the TranslateModule directly, instead use the [language testing utilities](/libs/lib-client/language/testing) under `@flogo-web/lib-client/language/testing`.
+
+Run tests
+
+```bash
+# from project root
+yarn test client
+```
+
+Run tests and watch for changes
+
+```bash
+# from project root
+yarn test client --watch
+```

docs/README.md

@@ -1,3 +1,6 @@
 # Documents
 
 - [Project Structure](./project-structure.md)
+- [Interaction with the Flogo engine](./engine-interaction.md)
+- [Models](./models.md)
+- [Plugins](./plugins.md)

docs/engine-interaction.md

@@ -1,64 +1,65 @@
 # Engine interaction
 
-Following documents how the flogo-web server interacts with the Flogo CLI to create, inspect and run the engine.
+This document explains how the flogo-web server interacts with the Flogo CLI to create, inspect and run the engine.
 
-* [Microservices](#microsevices)
+> :warning: For a better understanding of this document you will need first to get familiar with the usage of the [Flogo CLI](https://github.com/project-flogo/cli).
 
-## Microsevices
+> :computer: Most of the code that deals with the engine management can be found at [`apps/server/src/modules/engine`](https://github.com/TIBCOSoftware/flogo-web/tree/master/apps/server/src/modules/engine)
 
-> :computer: Most of the code that deals with the engine management can be found at [src/server/modules/engine`](https://github.com/TIBCOSoftware/flogo-web/tree/master/src/server/modules/engine)
-
-There's only one design time engine per flogo web instance. Flogo apps are not persisted into this engine, the flogo-web
+There's only one design time engine per Flogo Web instance. Flogo apps are not persisted into this engine, instead the Flogo Web
 has a database where it stores all the applications created and imported by the user. This is because for test-running a flow
 the engine doesn't read the app.json in the file system, instead it loads it dynamically from the flow service.
 
-To compile/build an app the app.json is required to be in the filesystem, for that a second engine project is created on-demand.
+To compile/build an app the `flogo.json` is required to be in the filesystem, for that a second engine project is created on-demand.
+
+The times when the Flogo Web server needs to interacto with Flogo CLI are:
+
+1. [When the engine project doesn't exist](#when-the-engine-project-doesnt-exist)
+1. [Every time the app starts](#every-time-the-app-starts)
+1. [When a user wants to install a new contribution](#when-a-user-wants-to-install-a-new-contribution)
+1. [When a user wants to download the binary for an app](#when-a-user-wants-to-download-the-binary-for-an-app)
 
 ### When the engine project doesn't exist
 
 The flogo-web server will try to find and existing engine in the file system, if it cannot find an engine then it will:
 
 1.  [Create a new design engine](#1.-create-a-new-design-engine)
-1.  [Install default contributions](#2.-install-default-contributions)
+1.  [Install contributions](#2.-install-contributions)
 
 #### 1. Create a new design engine
 
 By default the flogo-web server tries to find an engine project under `dist/local/engines/flogo-web` if not found it will
 create a new one by running:
 
 ```bash
-flogo create -f default-app.json -flv github.com/TIBCOSoftware/flogo-contrib/activity/log@master,github.com/TIBCOSoftware/flogo-lib/app/resource@master flogo-web
+flogo create -f default-app.json flogo-web
 ```
 
-* [default-app.json](https://github.com/TIBCOSoftware/flogo-web/blob/master/src/server/config/default-flogo.json) is a
+- [default-app.json](https://github.com/TIBCOSoftware/flogo-web/blob/master/apps/server/src/config/default-flogo.json) is a
   flogo.json with the minimum properties required by the flogo-cli create command. It doesn't declare any activities or
   triggers to allow the next step to install all the default contributions.
-* By default uses `@master` version to make sure the dev environment uses the latest code from flogo-lib and flogo-cli
-* The library version can be controlled by setting the `FLOGO_LIB_VERSION` or the `FLOGO_WEB_LIB_VERSION` environment variable.
-  Note that this only applies to engine creation and the engine will need to be re-created (i.e. deleted) to take the version changes.
 
-> :point_right: To ensure reproducible builds the production build process in the CI/CD pipeline automatically
-> assigns `FLOGO_LIB_VERSION` when a tagged version is being built. Ex. when building `v0.5.3` -flv parameter will be assigned to:
-> `github.com/TIBCOSoftware/flogo-contrib/activity/[email protected],github.com/TIBCOSoftware/flogo-lib/app/[email protected]`.
+By default a version for `project-flogo/core` is not specified, this is to make sure the dev environment uses the latest code from `project-flogo/core`.
+The version used for `priject-flogo/core` can be controlled by setting the `FLOGO_LIB_VERSION` or the `FLOGO_WEB_LIB_VERSION` environment variable.
+Note that this only applies to engine creation and the engine will need to be re-created (i.e. deleted) to take the version changes.
 
-#### 2. Install default contributions
-
-Once the design engine is created the default activities and triggers are installed into the engine by running:
+When the `FLOGO_LIB_VERSION` environment variable is specified the create command changes to:
 
 ```bash
-flogo install palette default-palette.json
+flogo create -f default-app.json --cv $FLOGO_LIB_VERSION flogo-web
 ```
 
-The `default-palette.json` describes the contributions to be included by default in the engine. The development environment palette
-is different than the palette that is installed in the production environment (the docker image).
+#### 2. Install contributions
 
-During the production build the `default-palette.json` is replaced by another palette created dynamically based on
-the activities and triggers that are available in the `flogo-contrib` repository.
+Once the design engine is created the default contributions (activities, triggers, functions and actions) are installed into the engine. This is done in two steps.
 
-The `default-palette.json` that has been checked into the repository and that is used for development is maintained manually.
-This is because installing all the OSS contributions takes a long time which is undesirable during development. Also, not all contributions
-are cross-platform compatible and given the variety of operating systems that the development team uses we need to make sure that
-the development palette can be used in windows, linux and macOS.
+First step is to create a dynamic [contribution bundle](https://github.com/project-flogo/cli/blob/master/docs/commands.md#install) out of the contribution references declared by the [Flogo Web plugins](./plugins.md). The dynamic contribution bundle is then installed into the engine by running:
+
+```bash
+flogo install --file /path/to/generated.plugin.bundle.json
+```
+
+The second step is to install the default contribution bundle. The [`default-bundle.json`](https://github.com/TIBCOSoftware/flogo-web/blob/master/apps/server/src/config/default-contrib-bundle.json) describes the contributions to be included by default in the engine and made available to be used in the UI. During engine creation the default bundle can be switched by setting the environment variable `FLOGO_WEB_DEFAULT_PALETTE` to point to the location of another bundle in the filesystem.
 
 ### Every time the app starts
 
@@ -69,36 +70,29 @@ When the server application starts and it can successfully find an instance of t
     `TESTER_ENABLED='true'` and also sets `TESTER_PORT` and `TESTER_SR_SERVER` based on the current app configuration. Then
     with that configuration issues the command:
 
-
 ```bash
 flogo build
 ```
 
 1.  Runs `flogo list -json` and based on the activities and triggers listed by that command it find their corresponding descriptors
     under `<engine>/src/vendor/<engine>` and loads them into the UI database.
 
-### Activity/trigger installation once the engine is created
+### When a user wants to install a new contribution
 
-1.  If activity/trigger is already installed it runs `flogo uninstall <ref>` where "ref" was provided by the user
+1.  If the contribution is already installed the server runs `flogo uninstall <ref>` where "ref" was provided by the user
 2.  Runs `flogo install <ref>`
 3.  Runs `flogo build` from inside the `<engine>` directory
 4.  Kill previous engine process running instance, and starts the new generated binary as explained in the previous section.
 
-### When you want to get the binary for an app
-
-1.  It serializes the application that the user wants to build and outputs it to a `flogo.json` file in a temporal location.
-2.  Runs
+### When a user wants to download the binary for an app
 
+1. It serializes the application that the user wants to build to a [Flogo Model JSON](https://github.com/project-flogo/core/blob/master/docs/model.md) and outputs it to a `flogo.json` file in a temporal location. The serialized format is the one expected by the Flogo Engine.
+2. A secondary engine project is created using the Flogo app that was exported in the previous step:
 
 ```bash
-flogo create -f <path-to-temp-flogo.json> -vendor <path-to-flogo-design-engine/src/vendor -flv <same as create step> engine-build
+flogo create -f <path-to-temp-flogo.json> --cv <same as create step> engine-build
 ```
 
-* vendor option allows to reuse the vendor directory of the existing design engine (`engines/flogo-web`), this way the engine creation
-  is faster as it doesn't require any additional network calls.
-* for now and while [flogo-cli#88](https://github.com/TIBCOSoftware/flogo-cli/issues/88) is resolved we need to specicy the same
-  `flv` value as the one used during the design engine creation.
-
 3.  From the generated directory runs: `flogo build -e -o`. Those options will embed the app.json and remove any contributions
     that are not being referenced by the app to make the binary as lightweight as possible.
 4.  For the previous step, if a target OS and architecture were defined then the environment variables `GOOS` and `GOARCH` will be

docs/models.md

@@ -0,0 +1,29 @@
+# Models
+
+This documents details the structure of the internal models in the Flogo Web UI and the differences when compared to the [Flogo core app model](https://github.com/project-flogo/core/blob/master/docs/model.md).
+
+The import and export process makes sure that a standard Flogo App Model can be converted into the internal Flogo Web app model and viceversa.
+
+## Unique Names and Id Normalization
+
+TBD
+
+## Apps
+
+[Application interface](../libs/core/src/lib/interfaces/app.ts)
+
+## Triggers
+
+[Triggers](../libs/core/src/lib/interfaces/trigger.ts)
+
+## Handlers
+
+[Handlers](../libs/core/src/lib/interfaces/trigger.ts)
+
+## Resources
+
+[Resources](../libs/core/src/lib/interfaces/resource.ts)
+
+## Contributions
+
+[Contributions](../libs/core/src/lib/interfaces/contributions)

docs/plugins.md

@@ -0,0 +1,27 @@
+# Plugins
+
+## What's a plugin
+
+## Server vs client
+
+## Server Plugins
+
+### How to create a server plugin
+
+### Server interface
+
+### Resource type
+
+### Resource hooks
+
+### How to register a server plugin
+
+## Client Plugins
+
+### How to create a client plugin
+
+### How to register a client plugin
+
+### Interacting with the client shell and its services
+
+<!-- Explanation about the plugin architecture -->

docs/project-structure.md

@@ -26,10 +26,49 @@ or depend on platform specific APIs (like browser DOM APIs or Node APIs).
 This is a summary of the current packages:
 
 - `/libs`
-  - `assets`: universal lib, contains application assets like images and fonts (`@flogo-web/assets`)
-  - `core`: universal lib, core logic and interfaces to be reused across the whole platform (`@flogo-web/core`)
-  - `lib-client`: contains client specific packages, usually angular modules (`@flogo-web/lib-client/<subcomponent>`)
-  - `lib-server`: contains server specific packages (`@flogo-web/lib-server/<subcomponent>`)
+  - `assets`: universal lib, contains application assets like images and fonts
+    - usage:
+    ```typescript
+    // typescript files
+    import { Foo } from '@flogo-web/assets';
+    ```
+    ```less
+    // .less files
+    @import '~@flogo-web/assets/styles';
+    ```
+  - `core`: universal lib, core logic and interfaces to be reused across the whole platform
+    - use:
+    ```typescript
+    // in typescript files
+    import { Foo } from '@flogo-web/core';
+    ```
+  - `lib-client`: contains client specific packages, mostly angular modules
+    - use:
+    ```typescript
+    // in typescript files
+    // import { Something } from '@flogo-web/lib-client/<subpackage>';
+    // For example:
+    import { DiagramComponent } from '@flogo-web/lib-client/diagram';
+    ```
+  - `lib-server`: contains server specific packages
+    - use:
+    ```typescript
+    // in typescript files
+    // import { Something } from '@flogo-web/lib-server/<subpackage>';
+    // For example:
+    import { Resource } from '@flogo-web/lib-server/core';
+    ```
     <!-- TODO: link to mapping docs when available: https://github.com/project-flogo/core/blob/master/docs/mapping.md -->
-  - `parser`: universal lib, can parse Flogo expressions used by the mapper module `@flogo-web/parser`
+  - `parser`: universal lib, can parse Flogo expressions used by the mapper module
+    - use:
+    ```typescript
+    // in typescript files
+    import { Resource } from '@flogo-web/parser';
+    ```
   - `plugins`: packages to extend the Flogo Web UI functionality and support different types of Flogo Actions
+    - use:
+    ```typescript
+    // in typescript files
+    // import { Example } from '@flogo-web/plugin-<type>-<server|client>';
+    import { Flow } from '@flogo-web/plugin-flow-server';
+    ```