Refactor the documentation structure

Fixes #1698

Moves all files around to make sure content is aligned into preferable reading order.
Also adds a very shallow introduction / architecture page.

flow-documentation/application-structure/tutorial-bootstrap.asciidoc → flow-documentation/advanced/tutorial-bootstrap.asciidoc

@@ -1,6 +1,6 @@
 ---
 title: Modifying the bootstrap page
-order: 5
+order: 2
 layout: page
 ---
 
@@ -10,7 +10,7 @@ ifdef::env-github[:outfilesuffix: .asciidoc]
 The application bootstrap page is created for you by the framework and normally there is no need to modify it.
 For instance Flow includes its internal JavaScripts to be able to provide its core functionality.
 Also it is possible to include additional JavaScripts, HTML imports and Style Sheets using annotations `@JavaScript`,
-`HtmlImport` and `@StyleSheet` (see <<tutorial-include-css#,Including Style Sheets>> and <<tutorial-importing#,Importing html/javascript>>).
+`HtmlImport` and `@StyleSheet` (see <<../importing-dependencies/tutorial-include-css#,Including Style Sheets>> and <<../importing-dependencies/tutorial-importing#,Importing html/javascript>>).
 
 Sometimes you may want to customize the page header and add there some additional data, e.g. custom `meta` tags.
 Such markup is required to enable your web page to become a rich object in a social graph using http://ogp.me/[OpenGraph protocol].
@@ -208,7 +208,7 @@ public class CustomBootstrapListener implements BootstrapListener {
 }
 ----
 
-Now this listener should be added to a `ServiceInitEvent` which is sent when a Vaadin service is initialized. Take a look on the <<../miscellaneous/tutorial-service-init-listener#,ServiceInitListener tutorial>> on how to configure it.
+Now this listener should be added to a `ServiceInitEvent` which is sent when a Vaadin service is initialized. Take a look on the <<../advanced/tutorial-service-init-listener#,ServiceInitListener tutorial>> on how to configure it.
 
 == Adding static HTML contents
 
@@ -244,7 +244,7 @@ public class Layout2 extends Div implements RouterLayout, PageConfigurator {
 }
 ----
 
- - using <<../application-structure/tutorial-bootstrap.asciidoc#bootstraplistener,`BootstrapListener>>#modifyBootstrapPage()`
+ - using <<../importing-dependencies/tutorial-bootstrap.asciidoc#bootstraplistener,`BootstrapListener>>#modifyBootstrapPage()`
 
 [source,java]
 ----

flow-documentation/miscellaneous/tutorial-dependency-filter.asciidoc → flow-documentation/advanced/tutorial-dependency-filter.asciidoc

@@ -1,13 +1,13 @@
 ---
 title: Modifying how dependencies are loaded with DependencyFilters
-order: 5
+order: 3
 layout: page
 ---
 
 ifdef::env-github[:outfilesuffix: .asciidoc]
 = Modifying how dependencies are loaded with DependencyFilters
 
-As seen on the tutorials about using `@JavaScript`, `@HtmlImport` and `@StyleSheet` (see <<../application-structure/tutorial-include-css#,Including Style Sheets>> and <<../application-structure/tutorial-importing#,Importing html/javascript>>), you can use annotations or an imperative API to add resources (or dependencies) to your application when needed. But in some cases, a more fine control is needed: for example, when bundling resources into multiple different bundles, you may want to control the application to import the right bundle when some specific resource is requested.
+As seen on the tutorials about using `@JavaScript`, `@HtmlImport` and `@StyleSheet` (see <<../importing-dependencies/tutorial-include-css#,Including Style Sheets>> and <<../importing-dependencies/tutorial-importing#,Importing html/javascript>>), you can use annotations or an imperative API to add resources (or dependencies) to your application when needed. But in some cases, a more fine control is needed: for example, when bundling resources into multiple different bundles, you may want to control the application to import the right bundle when some specific resource is requested.
 
 To control how the dependencies are loaded, and which files are effectively added or removed from the loading process, you can use DependencyFilters.
 

flow-documentation/miscellaneous/tutorial-dynamic-content.asciidoc → flow-documentation/advanced/tutorial-dynamic-content.asciidoc

@@ -1,6 +1,6 @@
 ---
 title: Dynamic Content
-order: 3
+order: 5
 layout: page
 ---
 

flow-documentation/miscellaneous/tutorial-loading-indicator.asciidoc → flow-documentation/advanced/tutorial-loading-indicator.asciidoc

@@ -1,6 +1,6 @@
 ---
 title: The Loading Indicator
-order: 4
+order: 6
 layout: page
 ---
 
@@ -91,7 +91,7 @@ seconds (300ms delay configured in java + 200ms animation delay).
 The next image illustrates an application with the modal curtain visible during loading
 (above) compared to the normal state (below).
 
-image:../images/modal_curtain.png[modal curtain]
+image:images/modal_curtain.png[modal curtain,700,700]
 
 == Displaying a Changing Loading Indicator
 

flow-documentation/miscellaneous/tutorial-service-init-listener.asciidoc → flow-documentation/advanced/tutorial-service-init-listener.asciidoc

@@ -1,14 +1,14 @@
 ---
 title: VaadinServiceInitListener
-order: 6
+order: 4
 layout: page
 ---
 
 ifdef::env-github[:outfilesuffix: .asciidoc]
 
 = VaadinServiceInitListener
 
-A VaadinServiceInitListener can be used to configure RequestHandlers, <<../application-structure/tutorial-bootstrap#,BootstrapListeners>> and <<tutorial-dependency-filter#,DependencyFilters>>.
+A VaadinServiceInitListener can be used to configure RequestHandlers, <<tutorial-bootstrap#,BootstrapListeners>> and <<tutorial-dependency-filter#,DependencyFilters>>.
 
 The listener should be added to a `ServiceInitEvent` which is sent when a Vaadin service is initialized.
 
@@ -43,7 +43,7 @@ This listener should be registered as a provider via Java SPI loading facility.
 This is a text file and it should contain the fully qualified name of the `ApplicationServiceInitListener` class on its own line.
 It allows to discover the  `ApplicationServiceInitListener` class, instantiate it and register as a service init listener for the application.
 
-image:../images/service-init-listener.png[The location of the configuration file]
+image:images/service-init-listener.png[The location of the configuration file]
 
 The content of the file should be like this:
 [source,text]

flow-documentation/data-provider/tutorial-flow-data-provider.asciidoc → flow-documentation/binding-data/tutorial-flow-data-provider.asciidoc

@@ -1,11 +1,11 @@
 ---
-title: Data Providers
-order: 1
+title: Showing a list of data with Data Providers
+order: 4
 layout: page
 ---
 
 [[datamodel.dataproviders]]
-= Data Providers
+= Showing a list of data with Data Providers
 
 A common pattern in applications is that the user is first presented with a list of items, from which she selects one or several items to continue working with.
 These items could be inventory records to survey, messages to respond to or blog drafts to edit or publish.

flow-documentation/flow-components/tutorial-flow-components-setup.asciidoc → flow-documentation/components/tutorial-flow-components-setup.asciidoc

@@ -1,15 +1,18 @@
 ---
-title: Setup your project to use Flow components
+title: Vaadin Components
 order: 2
 layout: page
 ---
 
-= Setup your project to use Flow components
+= Using Vaadin Components in Flow
 
-Flow provides pre-built server-side components for Vaadin webcomponents.
+There is a set of pre-built server-side components for Vaadin Web Components,
+such as `Button`, `TextField` and so on. Those components are part of
+the Vaadin 10 package, and are included as a dependency by default in Flow projects.
 
 Currently there are the following implementations:
 
+
 - https://github.com/vaadin/vaadin-button-flow[vaadin-button-flow]
 - https://github.com/vaadin/vaadin-checkbox-flow[vaadin-checkbox-flow]
 - https://github.com/vaadin/vaadin-combo-box-flow[vaadin-combo-box-flow]
@@ -19,6 +22,7 @@ Currently there are the following implementations:
 - https://github.com/vaadin/vaadin-grid-flow[vaadin-grid-flow]
 - https://github.com/vaadin/vaadin-icons-flow[vaadin-icons-flow]
 - https://github.com/vaadin/vaadin-iron-list-flow[vaadin-iron-list-flow]
+- https://github.com/vaadin/vaadin-notification-flow[vaadin-notification-flow]
 - https://github.com/vaadin/vaadin-ordered-layout-flow[vaadin-ordered-layout-flow]
 - https://github.com/vaadin/vaadin-progress-bar-flow[vaadin-progress-bar-flow]
 - https://github.com/vaadin/vaadin-split-layout-flow[vaadin-split-layout-flow]
@@ -50,6 +54,12 @@ any Flow project. Besides, you can add `vaadin-platform` dependency, if you need
 [NOTE]
 `vaadin.platform` releases regularly and you can check the version number https://github.com/vaadin/platform/releases[here]
 
+[NOTE]
+If you are not using the Vaadin 10 platform dependency and wish to use the Flow components, make sure it is
+properly configured to run with Polymer webcomponents. Please refer to
+<<../web-components/tutorial-webcomponent-basic#,Basic Integration of a Polymer Web Component>>
+for more information.
+
 = Overview
 
 A Flow component package consists of two main sections:
@@ -81,7 +91,10 @@ external web components' locations
 Due to current webjar https://github.com/webjars/webjars/issues[limitations],
 extra maven configuration (extra repository + bom file declaration) is required.
 
-== Maven configuration to use webjars
+== Maven configuration to use only single components
+
+If you don't want to take everything provided by the `com.vaadin:vaadin` dependency,
+you can also optionally declare single components as dependencies.
 
 The first step is to add the `bom` and the wanted `flow-component` (e.g. `vaadin-button-flow`)
 package to your project dependencies.
@@ -92,7 +105,7 @@ When using Maven you can add a the button component into your `pom.xml` as this:
 ----
 <repositories>
     <repository>
-        <id>flow-component-base</id>
+        <id>vaadin-prereleases</id>
         <url>https://maven.vaadin.com/vaadin-prereleases</url>
     </repository>
 </repositories>
@@ -119,7 +132,7 @@ When using Maven you can add a the button component into your `pom.xml` as this:
     </dependency>
 
     <!-- other dependencies -->
-</dependncies>
+</dependencies>
 ----
 
 == Maven configuration to exclude webjars
@@ -144,8 +157,8 @@ If webjar dependencies are not needed, they can be excluded from the project usi
     </dependency>
 
     <!-- other dependencies -->
-</dependncies>
+</dependencies>
 ----
 
-More documentation on webjars in can be found here: <<tutorial-flow-webjars#,WebJars in Flow>>
-General webJars usage manual is here: <<tutorial-how-to-use-webjars#, How to use webjars>>
+More documentation on webjars in can be found here: <<../web-components/tutorial-flow-webjars#,WebJars in Flow>>
+General webJars usage manual is here: <<../web-components/tutorial-how-to-use-webjars#, How to use webjars>>

flow-documentation/flow-components/tutorial-flow-grid.asciidoc → flow-documentation/components/tutorial-flow-grid.asciidoc

@@ -24,7 +24,7 @@ bandwidth, such as mobile devices.
 == Binding to Data
 
 `Grid` is normally used by binding it to a data provider,
-described in <<../data-provider/tutorial-flow-data-provider#,Data Providers>>.
+described in <<../binding-data/tutorial-flow-data-provider#,Data Providers>>.
 By default, it is bound to List of items. You can set the items with the `setItems()` method.
 
 For example, if you have a list of beans, you show them in a `Grid` as follows
@@ -595,7 +595,7 @@ grid.addColumn(new ComponentTemplateRenderer<>(person -> {
 [NOTE]
 Editing the grid's items requires refreshing it's `DataProvider`, like explained above in the
 <<Handling Events,template tutorial>>. More information about `DataProvider` can be found
-<<../data-provider/tutorial-flow-data-provider#,here>>.
+<<../binding-data/tutorial-flow-data-provider#,here>>.
 
 == Showing Item Details
 
@@ -640,7 +640,7 @@ Before jumping to the code, it's important to understand 2 key features of the s
 In-memory sorting is the sorting that is applied to the items that have been fetched from the backend, before returning them to the client.
 
 Backend sorting is a list of `QuerySortOrder` objects that can be used when implementing your own fetching logic within a `DataProvider`.
-You can check more details about the backend sorting <<../data-provider/tutorial-flow-data-provider#Sorting,here>>.
+You can check more details about the backend sorting <<../binding-data/tutorial-flow-data-provider#Sorting,here>>.
 
 You can have both in-memory and backend sorting at the same time, or you can configure them separately. Here is a list of options
 you can use to setup the sorting for your Grid:

flow-documentation/creating-components/tutorial-component-with-dependencies.asciidoc → flow-documentation/creating-components/tutorial-component-lifecycle-callbacks.asciidoc

@@ -1,10 +1,10 @@
 ---
-title: Creating a Component with External Dependencies
+title: Component Lifecycle Callbacks
 order: 7
 layout: page
 ---
 
-= Creating a Component with External Dependencies
+= Component Lifecycle Callbacks
 
 Sometimes the content of a component depends on resources that are not available
 during the construction of the component. You can postpone the content creation

flow-documentation/introduction/introduction-overview.asciidoc

@@ -0,0 +1,120 @@
+---
+title: Overview
+order: 1
+layout: page
+---
+
+= Introduction to Flow
+
+This chapter gives an overview to Vaadin Flow Architecture and introduces Flow's basic concepts.
+
+== Architecture
+
+Working with low-level web technologies is time consuming and hard.
+In Vaadin 10, all user interface elements are componentized into Web Components,
+meaning that they are de-coupled and sandboxed making web development easier than ever before.
+As part of Vaadin 10, Flow provides a type safe Java server-side API to use these Web Components.
+Flow provides automated bi-directional communication between the server and the browser giving Java developers full access to all of the modern web
+and makes it easier to connect the UI to data via a robust Java backend than using traditional REST based communication.
+
+image:images/v10-architecture.png[Vaadin 10 Architecture,1200,430]
+
+With Vaadin Flow you can access browsers APIs, Web Components, or even simple DOM-elements, directly from the server-side Java.
+When using Vaadin Flow, you do not need to understand how the client to server communication or the Web Components work.
+You can just focus on using and creating Components, which work at a much higher abstraction level.
+
+image:images/dom-to-java.png[dom-to-java,500,432]
+
+If necessary, you are also able to take full control over what gets send through the wire when creating components based on HTML templates.
+Flow provides two-way data binding so that when the UI is changed on the client or the server, it is automatically reflected to the other side.
+
+== Building UIs with Components
+
+The core of Vaadin Flow is UI Components, that are used to build interactive web apps and websites.
+On top of ready made components, there are powerful abstraction layers that can be used to create new components.
+
+=== Vaadin Components
+
+On the high abstraction layer, you will be super productive and build your UI using the Java APIs of Vaadin Components based on the Vaadin Elements Web Components.
+This way you don't have to write or understand any JavaScript or HTML, and CSS is only necessary to give your App the look and feel you want to.
+
+// CODE SNIPPET //
+
+// LINK TO ACTUAL CHAPTER //
+
+=== Composing new Components in 100% Java
+
+On the next abstraction layer you can easily create new components by customizing and mixing existing components,
+made possible by light-weight component architecture and access to the DOM and browser APIs from server side.
+This allows you to work out issues and customize things, while still staying on the server side
+and leveraging Flows automated communication layer between the browser and the server.
+
+// CODE SNIPPET //
+
+// LINKS TO CHAPTERS //
+
+=== Integrating a Web Component
+
+With Vaadin Flow you can take any Web Component, and create the Java API for them and start using them in your projects.
+
+// CODE SNIPPET //
+
+// LINK TO CHAPTER //
+
+=== Building Components with HTML Templates
+
+On the lowest level, it is possible to take full control of the DOM and the communication, by creating components as HTML templates,
+and creating a server side Java class that encapsulates them into reusable components with a high-level API. To help build the templates, Flow provides:
+
+* a Model that allows you to share and synchronize data between the Java and the HTML template
+* a server side representation of the client-side DOM tree to dynamic modifications to the template
+* a type-safe Java RPC API for interacting with JavaScript in the browser.
+
+// CODE SNIPPET //
+
+// LINK TO CHAPTER //
+
+// == Router TODO should provide short intro to router and links //
+
+== How Flow Components Work
+
+Flow allows Java code to control the DOM in the user's browser by having a server-side representation of the same DOM tree.
+All changes are automatically synchronized to the real DOM tree in the browser.
+
+The DOM tree is built up from `Element` instances, each one representing a DOM element in the browser.
+The root of the server-side DOM tree is the `Element` of the `UI` instance, accessible using `ui.getElement()`.
+This element represents the `<body>` tag.
+
+Elements on the server are implemented as flyweight instances.
+This means that you cannot compare elements using `==` and `!=`.
+Instead, `element.equals(otherElement)` should be used to check whether two instances refer to the same DOM element in the browser.
+
+=== Element Hierarchy
+
+A web application is structured as a tree of elements with the root being the element of the `UI` instance.
+An element can be added as a child of another element using methods such as `element.appendChild(Element)` for adding an element to the end of a parent's child list or `element.insertChild(int, Element)` for adding to any position in the child list.
+
+The element hierarchy can be navigated upwards using `element.getParent()` and downwards using `element.getChildCount()` and `element.getChild(int)`.
+
+=== Component Hierarchy
+The component hierarchy provides an higher level abstraction on top of the element hierarchy.
+A component consists of a root element and can optionally contain any number of child elements.
+Components can be added inside other components using methods such as `UI.add(Component)`, provided the parent component supports child components.
+
+Composite is a special kind of component which does not have a root element of its own but instead encapsulates another component.
+The main use case for a composite is to combine existing components into new components while hiding the original component API.
+
+The component hierarchy can be navigated upwards using `component.getParent()` and downwards using `component.getChildren()`.
+The component hierarchy is constructed based on the element hierarchy, so they are always in sync.
+
+=== Templates
+Instead of writing Java code for building the DOM from individual elements,
+it's also possible to use the `Template` component to define the overall DOM structure in an HTML template file and then use a model to control the contents of the elements.
+
+In addition to giving a clearer overview of the structure of a Component, the template functionality does also help improve performance –
+the same template definition is reused for all component instance using the same template file. This means that less memory is used on the server and less data needs to be sent to the browser.
+
+== Hello World in Flow
+
+<<tutorial-hello-world#,The next page>> shows the simples possible way of building a Hello World application with Flow.
+