diff --git a/docs/site/LoopBack-3.x.md b/docs/site/LoopBack-3.x.md
index 1a6bca4eebe3..8e5f42163084 100644
--- a/docs/site/LoopBack-3.x.md
+++ b/docs/site/LoopBack-3.x.md
@@ -12,101 +12,9 @@ you're an existing LoopBack user, read
[Crafting LoopBack 4](Crafting-LoopBack-4.html) to understand the motivations,
strategy, and innovations behind this exciting new version.
-This article will help existing users understand LoopBack 4:
+For more information on the difference between LoopBack 3 and LoopBack 4, see
+[Understanding the differences between LoopBack 3 and LoopBack 4](Understanding-the-differences.md).
-- How to connect LoopBack 3.x concepts to LoopBack 4 terms
-- What's new and exciting in LoopBack 4
-- What's on the roadmap to achieve functional parity
-
-## Overview
-
-At high-level, LoopBack 3.x applications consist of three big "parts"
-
-- Persistence layer (this includes talking to backend services like SOAP/REST)
-- Outwards facing REST API
-- App-wide setup - Express middleware, boot scripts, etc.
-
-In the persistence layer, users can contribute the following artifacts:
-
-1. Definitions of Model data types (properties, validations)
-2. Definition of data sources
-3. Configuration of models (which datasource are they attached to)
-4. Operation hooks
-
-At the public API side, users can define:
-
-1. Which built-in methods should be exposed (think of
- `disableRemoteMethodByName`)
-2. Custom remote methods
-3. before/after/afterError hooks at application-level
-4. before/after/afterError hooks at model-level
-5. before/after/afterError hooks at model method level
-
-LoopBack 4 was intentionally designed to allow users to choose their own
-ORM/persistence solution. The juggler from LoopBack 3 has been packaged into
-`@loopback/repository` so that it's possible for users to reuse their existing
-model definitions, migrating their application incrementally.
-
-## Concept/feature mapping
-
-In Loopback 3.x (and earlier), models were responsible for both accessing data
-in other systems (databases, SOAP services, etc.) and providing the
-application's external REST API. This made it easy to quickly build a REST
-interface for an existing database, but difficult to customize the REST API and
-fine-tune it to the needs of application clients.
-
-LoopBack 4 is moving to the well-known Model-(View-)Controller pattern, where
-the code responsible for data access and manipulation is separated from the code
-responsible for implementing the REST API.
-
-[loopback4-example-microservices](https://github.com/strongloop/loopback4-example-microservices)
-demonstrates this loose coupling. Facade is the top-level service that serves
-the account summary API, and is dependent on the three services Account,
-Customer, and Transaction. But the facade only aggregates the calls to the three
-services, and is not tightly coupled with the service implementation; that's why
-it is independent of the three services. We can define the APIs in facade the
-way we want. Thus, code responsible for data access and manipulation is
-separated from the code responsible for implementing client side APIs.
-
-| Concept/Feature | LoopBack 3.x | LoopBack 4 |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Programming Language | Built with JavaScript ES5
Node.js callback | TypeScript 2.6.x & JavaScript ES2016/2017
Promise & Async/Await |
-| Core foundation | Express with LoopBack extensions | Home-grown IoC container |
-| Model Definition | Models can be defined with JavaScript or JSON | Models can be defined with TypeScript/JavaScript/JSON(TBA) |
-| Model Persistence | A model can be attached to a datasource backed by a connector that implements CRUD operations | [Repositories](https://github.com/strongloop/loopback-next/tree/master/packages/repository) are introduced to represent persistence related operations; a repository binds a model metadata to a datasource |
-| Model Relation | Relations can be defined between models | (TBA) Relations can be defined between models but they will be realized between repositories |
-| Model Remoting | JavaScript/JSON remoting metadata is used to describe method signatures and their mapping to REST/HTTP
Swagger specs are generated after the fact | Remoting metadata can be supplied by OpenAPI JSON/YAML documents or generated automatically through TypeScript decorators |
-| API Spec | Swagger 2.0 | OpenAPI Spec 3.0 and potentially other API specs such as GraphQL, gRPC, etc. |
-| API Explorer | Built-in UI based on swagger-ui (/explorer) | (Beta) Expose OpenAPI specs and a browser redirect to Swagger UI hosted by loopback.io |
-| DataSource | JSON and JS | JSON/JS/TypeScript |
-| Connector | Plain JS | JS and TypeScript (TBA) |
-| Mixin | Use a utility to add methods from the mixin to the target model class | Use ES2015 mixin classes pattern supported by [TypeScript 2.2 and above](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html) |
-| Middleware | Express middleware with phase-based registration and ordering | Sequence consisting of actions |
-| Boot script | Scripts to be invoked during bootstrapping | (TBD) |
-| Remote hooks | Before/After hooks for remote methods | Sequence/actions |
-| CRUD operation hooks | Hooks for CRUD operations | Sequence/actions |
-| Built-in models | Built-in User/AccessToken/Application/ACL/Role/RoleMapping for AAA | (TBD) |
-| Authentication | User model as the login provider
loopback-component-passport | (TBA) Authentication component ([@loopback/authentication](https://github.com/strongloop/loopback-next/tree/master/packages/authentication)) with extensibility to strategy providers |
-| Authorization | Use built-in User/Application/AccessToken model for identity and ACL/Role/RoleMapping for authorization | (TBD) Authorization component |
-| Component | A very simple implementation to configure and invoke other modules | A fully-fledged packaging model that allows contribution of extensions from other modules |
-| Tooling | loopback-cli and API Connect UI | [@loopback/cli](https://github.com/strongloop/loopback-next/tree/master/packages/cli) |
-
-## What's new and exciting in LoopBack 4
-
-Some of the highlights of LoopBack 4 include:
-
-- Leverage TypeScript for better code quality and productivity
-- Unify and simplify the asynchronous programming model/style around Promise and
- Async/Await
-- Implement an IoC Container with Dependency Injection for better visibility,
- extensibility and composability
-- Introduce Component as packaging model for extensions that can be plugged into
- LoopBack 4 applications
-- Make everything else as components (REST, Authentication, and Authorization)
-- Divide the responsibilities of LoopBack models into
- - Controllers: handle incoming API requests
- - Repositories: provide access to datasources
- - Models: define schemas for business objects
- - Services: interact with existing REST APIs, SOAP Web Services, and other
- forms of services/microservices
-- Refactor the ORM into separate modules for different concerns
+To facilitate migration between LoopBack 3 and LoopBack 4, you can mount your
+LoopBack 3 application on top of a LoopBack 4 project. See
+[Migrating from LoopBack 3](Migrating-from-LoopBack-3.md) for details.
diff --git a/docs/site/Migrating-from-LoopBack-3.md b/docs/site/Migrating-from-LoopBack-3.md
new file mode 100644
index 000000000000..54d7a8c9b7e3
--- /dev/null
+++ b/docs/site/Migrating-from-LoopBack-3.md
@@ -0,0 +1,81 @@
+---
+lang: en
+title: 'Migrating from LoopBack 3'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Migrating-from-LoopBack-3.html
+---
+
+For current LoopBack 3 users who want to migrate to LoopBack 4, LoopBack 4
+offers a way to mount your LoopBack 3 application in a LoopBack 4 project. By
+adding your application this way, the application's REST API is included in the
+OpenAPI spec provided by the LoopBack 4 application. This also means that the
+LoopBack 3 application's models can be used with the LoopBack 4 REST API
+Explorer.
+
+## Mounting the LoopBack 3 Application in a LoopBack 4 Project
+
+{% include note.html content="
+If you are not familiar with LoopBack 4, visit
+[Getting started](Getting-started.md) for an introduction.
+" %}
+
+Follow
+[this tutorial](https://github.com/strongloop/loopback-next/tree/master/examples/lb3-application#tutorial)
+that goes through the full steps to mount your application.
+
+To see an example of a mounted application, see
+[lb3-application](https://github.com/strongloop/loopback-next/tree/master/examples/lb3-application)
+which mounts the
+[CoffeeShop example](https://github.com/strongloop/loopback-getting-started),
+built from LoopBack 3, in a LoopBack 4 project.
+
+{% include warning.html content="
+An important thing to note is that LoopBack 3 applications produce Swagger
+(OpenAPI version 2), whereas LoopBack 4 produces OpenAPI version 3.
+`Lb3AppBooterComponent` converts the Swagger spec from the mounted LoopBack 3
+application to OpenAPI v3 and adds it to the LoopBack 4 project's OpenAPI v3
+spec.
+" %}
+
+### Options
+
+[`Lb3AppBooterComponent`](https://loopback.io/doc/en/lb4/apidocs.booter-lb3app.lb3appbootercomponent.html)
+comes with the option to either mount the full LoopBack 3 application or only
+the rest routes. Default `mode` is the full application (`fullApp`).
+
+{% include code-caption.html content="src/application.ts" %}
+
+```ts
+this.bootOptions = {
+ lb3app: {
+ mode: 'restRouter', // only REST routes are mounted
+ },
+};
+```
+
+To change the path where the main LoopBack 3 application server file is stored,
+you can modify the `path`. Default `path` is `../lb3app/server/server`.
+
+{% include code-caption.html content="src/application.ts" %}
+
+```ts
+this.bootOptions = {
+ lb3app: {
+ path: '../coffee-shop/server/server', // server file is found under this path
+ },
+};
+```
+
+Finally, you can modify the `restApiRoot` when only mounting the rest router of
+your LoopBack 3 application. Default is `restApiRoot` is `/api`.
+
+{% include code-caption.html content="src/application.ts" %}
+
+```ts
+this.bootOptions = {
+ lb3app: {
+ restApiRoot: '/coffees',
+ },
+};
+```
diff --git a/docs/site/Understanding-the-differences.md b/docs/site/Understanding-the-differences.md
new file mode 100644
index 000000000000..c38b36f63ade
--- /dev/null
+++ b/docs/site/Understanding-the-differences.md
@@ -0,0 +1,109 @@
+---
+lang: en
+title: 'Understanding the differences between LoopBack 3 and LoopBack 4'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Understanding-the-differences.html
+---
+
+This article will help existing users understand LoopBack 4:
+
+- How to connect LoopBack 3.x concepts to LoopBack 4 terms
+- What's new and exciting in LoopBack 4
+
+## Overview
+
+At high-level, LoopBack 3.x applications consist of three big "parts"
+
+- Persistence layer (this includes talking to backend services like SOAP/REST)
+- Outwards facing REST API
+- App-wide setup - Express middleware, boot scripts, etc.
+
+In the persistence layer, users can contribute the following artifacts:
+
+1. Definitions of Model data types (properties, validations)
+2. Definition of data sources
+3. Configuration of models (which datasource are they attached to)
+4. Operation hooks
+
+At the public API side, users can define:
+
+1. Which built-in methods should be exposed (think of
+ `disableRemoteMethodByName`)
+2. Custom remote methods
+3. before/after/afterError hooks at application-level
+4. before/after/afterError hooks at model-level
+5. before/after/afterError hooks at model method level
+
+LoopBack 4 was intentionally designed to allow users to choose their own
+ORM/persistence solution. The juggler from LoopBack 3 has been packaged into
+`@loopback/repository` so that it's possible for users to reuse their existing
+model definitions, migrating their application incrementally.
+
+## Concept/feature mapping
+
+In Loopback 3.x (and earlier), models were responsible for both accessing data
+in other systems (databases, SOAP services, etc.) and providing the
+application's external REST API. This made it easy to quickly build a REST
+interface for an existing database, but difficult to customize the REST API and
+fine-tune it to the needs of application clients.
+
+LoopBack 4 is moving to the well-known Model-(View-)Controller pattern, where
+the code responsible for data access and manipulation is separated from the code
+responsible for implementing the REST API.
+
+[loopback4-example-microservices](https://github.com/strongloop/loopback4-example-microservices)
+demonstrates this loose coupling. Facade is the top-level service that serves
+the account summary API, and is dependent on the three services Account,
+Customer, and Transaction. But the facade only aggregates the calls to the three
+services, and is not tightly coupled with the service implementation; that's why
+it is independent of the three services. We can define the APIs in facade the
+way we want. Thus, code responsible for data access and manipulation is
+separated from the code responsible for implementing client side APIs.
+
+| Concept/Feature | LoopBack 3.x | LoopBack 4 |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Programming Language | Built with JavaScript ES5
Node.js callback | TypeScript 2.6.x & JavaScript ES2016/2017
Promise & Async/Await |
+| Core foundation | Express with LoopBack extensions | Home-grown IoC container |
+| Model Definition | Models can be defined with JavaScript or JSON | Models can be defined with TypeScript/JavaScript/JSON(TBA) |
+| Model Persistence | A model can be attached to a datasource backed by a connector that implements CRUD operations | [Repositories](https://github.com/strongloop/loopback-next/tree/master/packages/repository) are introduced to represent persistence related operations; a repository binds a model metadata to a datasource |
+| Model Relation | Relations can be defined between models | (TBA) Relations can be defined between models but they will be realized between repositories |
+| Model Remoting | JavaScript/JSON remoting metadata is used to describe method signatures and their mapping to REST/HTTP
Swagger specs are generated after the fact | Remoting metadata can be supplied by OpenAPI JSON/YAML documents or generated automatically through TypeScript decorators |
+| API Spec | Swagger 2.0 | OpenAPI Spec 3.0 and potentially other API specs such as GraphQL, gRPC, etc. |
+| API Explorer | Built-in UI based on swagger-ui (/explorer) | (Beta) Expose OpenAPI specs and a browser redirect to Swagger UI hosted by loopback.io |
+| DataSource | JSON and JS | JSON/JS/TypeScript |
+| Connector | Plain JS | JS and TypeScript (TBA) |
+| Mixin | Use a utility to add methods from the mixin to the target model class | Use ES2015 mixin classes pattern supported by [TypeScript 2.2 and above](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html) |
+| Middleware | Express middleware with phase-based registration and ordering | Sequence consisting of actions |
+| Boot script | Scripts to be invoked during bootstrapping | (TBD) |
+| Remote hooks | Before/After hooks for remote methods | Sequence/actions |
+| CRUD operation hooks | Hooks for CRUD operations | Sequence/actions |
+| Built-in models | Built-in User/AccessToken/Application/ACL/Role/RoleMapping for AAA | (TBD) |
+| Authentication | User model as the login provider
loopback-component-passport | (TBA) Authentication component ([@loopback/authentication](https://github.com/strongloop/loopback-next/tree/master/packages/authentication)) with extensibility to strategy providers |
+| Authorization | Use built-in User/Application/AccessToken model for identity and ACL/Role/RoleMapping for authorization | (TBD) Authorization component |
+| Component | A very simple implementation to configure and invoke other modules | A fully-fledged packaging model that allows contribution of extensions from other modules |
+| Tooling | loopback-cli and API Connect UI | [@loopback/cli](https://github.com/strongloop/loopback-next/tree/master/packages/cli) |
+
+## What's new and exciting in LoopBack 4
+
+Some of the highlights of LoopBack 4 include:
+
+- Leverage TypeScript for better code quality and productivity
+- Unify and simplify the asynchronous programming model/style around Promise and
+ Async/Await
+- Implement an IoC Container with Dependency Injection for better visibility,
+ extensibility and composability
+- Introduce Component as packaging model for extensions that can be plugged into
+ LoopBack 4 applications
+- Make everything else as components (REST, Authentication, and Authorization)
+- Divide the responsibilities of LoopBack models into
+ - Controllers: handle incoming API requests
+ - Repositories: provide access to datasources
+ - Models: define schemas for business objects
+ - Services: interact with existing REST APIs, SOAP Web Services, and other
+ forms of services/microservices
+- Refactor the ORM into separate modules for different concerns
+
+As LoopBack 4 continues to grow, more features are continuously added. You can
+check out our [blog](https://strongloop.com/strongblog/tag_LoopBack.html) to
+keep up with these new features.
diff --git a/docs/site/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml
index c726675b1cc7..8e5cc07c0ed7 100644
--- a/docs/site/sidebars/lb4_sidebar.yml
+++ b/docs/site/sidebars/lb4_sidebar.yml
@@ -285,6 +285,15 @@ children:
- title: 'For LoopBack 3.x users'
url: LoopBack-3.x.html
output: 'web, pdf'
+ children:
+
+ - title: 'Understanding the differences between LoopBack 3 and LoopBack 4'
+ url: Understanding-the-differences.html
+ output: 'web, pdf'
+
+ - title: 'Migrating from LoopBack 3'
+ url: Migrating-from-LoopBack-3.html
+ output: 'web, pdf'
- title: 'Command-line interface'
url: Command-line-interface.html
diff --git a/examples/lb3-application/README.md b/examples/lb3-application/README.md
index f6b0bb51b0ee..5119e3537c6c 100644
--- a/examples/lb3-application/README.md
+++ b/examples/lb3-application/README.md
@@ -11,6 +11,8 @@ new LoopBack 4 project.
$ lb4 app
```
+ Fill out the prompts as they fit your project and leave all features enabled.
+
2. Create a new directory `lb3app` from the root of your LoopBack 4 application
and copy your existing LoopBack 3 application there. You should end up with
the following directory layout: