docs(general): add readme

Author: manfredsteyer

.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+    "spellright.language": [
+        "en"
+    ],
+    "spellright.documentTypes": [
+        "markdown",
+        "latex",
+        "plaintext"
+    ]
+}

README.md

@@ -1,76 +1,3 @@
-# AngularArchitects
+# @angular-architects/ddd -- DDD Plugin for Nx
 
-This project was generated using [Nx](https://nx.dev).
-
-<p align="center"><img src="https://raw.githubusercontent.com/nrwl/nx/master/nx-logo.png" width="450"></p>
-
-🔎 **Nx is a set of Extensible Dev Tools for Monorepos.**
-
-## Adding capabilities to your workspace
-
-Nx supports many plugins which add capabilities for developing different types of applications and different tools.
-
-These capabilities include generating applications, libraries, etc as well as the devtools to test, and build projects as well.
-
-Below are some plugins which you can add to your workspace:
-
-- [React](https://reactjs.org)
-  - `npm install --save-dev @nrwl/react`
-- Web (no framework frontends)
-  - `npm install --save-dev @nrwl/web`
-- [Angular](https://angular.io)
-  - `npm install --save-dev @nrwl/angular`
-- [Nest](https://nestjs.com)
-  - `npm install --save-dev @nrwl/nest`
-- [Express](https://expressjs.com)
-  - `npm install --save-dev @nrwl/express`
-- [Node](https://nodejs.org)
-  - `npm install --save-dev @nrwl/node`
-
-## Generate an application
-
-Run `nx g @nrwl/react:app my-app` to generate an application.
-
-> You can use any of the plugins above to generate applications as well.
-
-When using Nx, you can create multiple applications and libraries in the same workspace.
-
-## Generate a library
-
-Run `nx g @nrwl/react:lib my-lib` to generate a library.
-
-> You can also use any of the plugins above to generate libraries as well.
-
-Libraries are sharable across libraries and applications. They can be imported from `@angular-architects/mylib`.
-
-## Development server
-
-Run `nx serve my-app` for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.
-
-## Code scaffolding
-
-Run `nx g @nrwl/react:component my-component --project=my-app` to generate a new component.
-
-## Build
-
-Run `nx build my-app` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build.
-
-## Running unit tests
-
-Run `nx test my-app` to execute the unit tests via [Jest](https://jestjs.io).
-
-Run `nx affected:test` to execute the unit tests affected by a change.
-
-## Running end-to-end tests
-
-Run `ng e2e my-app` to execute the end-to-end tests via [Cypress](https://www.cypress.io).
-
-Run `nx affected:e2e` to execute the end-to-end tests affected by a change.
-
-## Understand your workspace
-
-Run `nx dep-graph` to see a diagram of the dependencies of your projects.
-
-## Further help
-
-Visit the [Nx Documentation](https://nx.dev) to learn more.
+see [libs/ddd/readme.md](libs/ddd/README.md)

libs/ddd/README.md

@@ -1,9 +1,30 @@
 # @angular-architects/ddd -- DDD Plugin for Nx
 
+This plugin installs some schematics which automate slicing your Nx workspace into domains and layers according to Nrwl's best practices and our ideas about [client-side DDD with Angular](https://www.softwarearchitekt.at/aktuelles/sustainable-angular-architectures-1/):
+
+![domains and layers](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/ddd.png?raw=true)
+
+The generated access restrictions prevent unwanted access between libraries respecting layers and domains:
+
+![access restrictions](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/linting-2.png?raw=true)
+
+## Features
+
+- 🗺️ Generating domains with domain libraries including a facades, models, and data services
+- ⚙️ Generating feature libraries including a feature components using the facades
+- 🙅‍♂️ Adding linting rules for access restrictions between domains as proposed by Nrwl
+- 🙅‍♀️ Adding linting rules for access restrictions between layers as proposed by Nrwl
+
+## Usage
+
+Add this plugin to an Nx workspace:
+
 ```
-npm i 
+ng add @angular-architects/ddd
 ```
 
+Add domains and features:
+
 ```
 ng g @angular-architects/ddd:domain booking
 ng g @angular-architects/ddd:domain boarding
@@ -12,6 +33,57 @@ ng g @angular-architects/ddd:feature cancel --domain booking --app flight-app
 ng g @angular-architects/ddd:feature manage --domain boarding --app flight-app
 ```
 
+This example assumes that you have an app ``flight-app`` in place.
+
+These schematics also wire up the individual libs. To see the result, create a dependency graph:
+
 ```
 npm run dep-graph
-```
+```
+
+![dependency graph](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/ddd.png?raw=true)
+
+To see that the skeleton works end-to-end, call the generated feature component in your ``app.component.html``:
+
+```html
+<booking-search></booking-search>
+```
+
+You don't need any TypeScript or Angular imports. The plugin already took care about that. After running the example, you should see something like this:
+
+![Result proving that the generated skeleton works end-to-end](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/result.png?raw=true)
+
+## Generated Structure
+
+The included schematics generate a folder for each domain. This folder contains feature libs as well as a library with the domain logic:
+
+![Folder per Domain](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/ddd-libs.png?raw=true)
+
+The domain layer is subdivided into three parts:
+
+![Structured Domain Layer](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/domain-layer.png?raw=true)
+
+### Generated Structure for Domain Library
+
+- **application:** Contains application services. This is a DDD term for what we call facades in Angular nowadays. They orchestrate everything for a use case given so that a feature component only needs to communicate with one such facade. Also, it hides details for state management. While the generates facades just use a ``BehaviorSubject``, feel free to add a library like NGRX underneath. As such a modifications changes nothing from the component's perspective, you can use facades to introduce NGRX later on demand.
+- **entities:** Client-side data model including logic operating on it (like validations).
+- **infrastructure:** Services for communicating with the backend.
+
+## Consider Automatically Checking Access Restrictions
+
+As the access restrictions defined with Nx use linting, you can check against them at the command line too. Hence, you might consider including this into your automated build process.
+
+![Access restrictions via linting](https://github.com/angular-architects/nx-ddd-plugin/blob/master/libs/ddd/assets/linting-3.png?raw=true)
+
+## Example Application
+
+see https://github.com/angular-architects/ddd-demo
+
+## Credits
+
+- [Nx](https://nx.dev/web)
+- [Nrwl's eBook about monorepos and best practices](https://go.nrwl.io/angular-enterprise-monorepo-patterns-new-book)
+- [Recording of session about this architecture](https://www.youtube.com/watch?v=94HFD391zkE&t=1s)
+- [Article series about DDD with Angular](https://www.softwarearchitekt.at/aktuelles/sustainable-angular-architectures-1/)
+- [Our eBook about this architecture](https://leanpub.com/enterprise-angular)
+- [Thomas Burlison's article about facades in Angular](https://medium.com/@thomasburlesonIA/push-based-architectures-with-rxjs-81b327d7c32d)

libs/ddd/assets/ddd.png

@@ -1,6 +1,6 @@
 {
   "name": "@angular-architects/ddd",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "author": "Manfred Steyer",
   "description": "Nx plugin for structuring a monorepo with domains and layers",
   "repository": {