Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674

1 files changed, 162 insertions, 0 deletions

diff --git a/documentation/architecture/architecture-overview.asciidoc b/documentation/architecture/architecture-overview.asciidoc
new file mode 100644
index 0000000000..4ff34c453c
--- /dev/null
+++ b/documentation/architecture/architecture-overview.asciidoc
@@ -0,0 +1,162 @@
+---
+title: Overview
+order: 1
+layout: page
+---
+
+[[architecture.overview]]
+= Overview
+
+Vaadin provides two development models for web applications: for the client-side
+(the browser) and for the server-side. The server-driven development model is
+the more powerful one, allowing application development solely on the
+server-side, by utilizing an AJAX-based Vaadin Client-Side Engine that renders
+the user interface in the browser. The client-side model allows developing
+widgets and applications in Java, which are compiled to JavaScript and executed
+in the browser. The two models can share their UI widgets, themes, and back-end
+code and services, and can be mixed together easily.
+
+[[figure.architecture.detailed]]
+.Vaadin Runtime Architecture
+image::img/architecture-detailed-hi.png[]
+
+<<figure.architecture.detailed>> gives a basic illustration of the client-side
+and server-side communications, in a running situation where the page with the
+client-side code (engine or application) has been initially loaded in the
+browser.
+
+Vaadin Framework consists of a __server-side API__, a __client-side API__, a
+horde of __user interface components/widgets__ on the both sides, __themes__ for
+controlling the appearance, and a __data model__ that allows binding the
+server-side components directly to data. For client-side development, it
+includes the Vaadin Compiler, which allows compiling Java to JavaScript.
+
+A server-side Vaadin application runs as a servlet in a Java web server, serving
+HTTP requests. The [classname]#VaadinServlet# is normally used as the servlet
+class. The servlet receives client requests and inteprets them as events for a
+particular user session. Events are associated with user interface components
+and delivered to the event listeners defined in the application. If the UI logic
+makes changes to the server-side user interface components, the servlet renders
+them in the web browser by generating a response. The client-side engine running
+in the browser receives the responses and uses them to make any necessary
+changes to the page in the browser.
+
+The major parts of the server-driven development architecture and their function
+are as follows:
+
+User Interface:: Vaadin applications provide a user interface for the user to interface with the
+business logic and data of the application. At technical level, the UI is
+realized as a __UI__ class that extends [classname]#com.vaadin.ui.UI#. Its main
+task is to create the initial user interface out of UI components and set up
+event listeners to handle user input. The UI can then be loaded in the browser
+using an URL, or can be embedded to any HTML page. For detailed information
+about implementing a [classname]#UI#, see
+<<dummy/../../../framework/application/application-overview.asciidoc#application.overview,"Writing
+a Server-Side Web Application">>.
+
++
+Please note that the term "UI" is used throughout this book to refer both to the
+general UI concept as well as the technical UI class concept.
+
+User Interface Components/Widgets:: ((("component")))
+((("widget")))
+((("field")))
+The user interface of a Vaadin application consists of components that are
+created and laid out by the application. Each server-side component has a
+client-side counterpart, a " __widget__", by which it is rendered in the browser
+and with which the user interacts. The client-side widgets can also be used by
+client-side applications. The server-side components relay these events to the
+application logic. Field components that have a value, which the user can view
+or edit, can be bound to a data source (see below). For a more detailed
+description of the UI component architecture, see
+<<dummy/../../../framework/components/components-overview.asciidoc#components.overview,"User
+Interface Components">>.
+
+Client-Side Engine:: ((("Client-Side
+Engine")))
+((("Google Web
+Toolkit")))
+((("HTTP")))
+The Client-Side Engine of Vaadin manages the rendering of the UI in the web
+browser by employing various client-side __widgets__, counterparts of the
+server-side components. It communicates user interaction to the server-side, and
+then again renders the changes in the UI. The communications are made using
+asynchronous HTTP or HTTPS requests. See
+<<dummy/../../../framework/architecture/architecture-client-side#architecture.client-side,"Client-Side
+Engine">>.
+
+Vaadin Servlet:: ((("VaadinServlet")))
+Server-side Vaadin applications work on top of the Java Servlet API (see
+<<dummy/../../../framework/architecture/architecture-technology#architecture.technology.servlet,"Java
+Servlets">>). The Vaadin servlet, or more exactly the [classname]#VaadinServlet#
+class, receives requests from different clients, determines which user session
+they belong to by tracking the sessions with cookies, and delegates the requests
+to their corresponding sessions. You can customize the Vaadin servlet by
+extending it.
+
+Themes:: ((("theme")))
+((("CSS")))
+((("Sass")))
+((("HTML
+templates")))
+Vaadin makes a separation between the appearance and component structure of the
+user interface. While the UI logic is handled as Java code, the presentation is
+defined in __themes__ as CSS or Sass. Vaadin provides a number of default
+themes. User themes can, in addition to style sheets, include HTML templates
+that define custom layouts and other resources, such as images and fonts. Themes
+are discussed in detail in
+<<dummy/../../../framework/themes/themes-overview.asciidoc#themes.overview,"Themes">>.
+
+Events:: ((("events")))
+Interaction with user interface components creates events, which are first
+processed on the client-side by the widgets, then passed all the way through the
+HTTP server, Vaadin servlet, and the user interface components to the event
+listeners defined in the application. See
+<<dummy/../../../framework/architecture/architecture-events#architecture.events,"Events
+and Listeners">>.
+
+Server Push:: ((("server
+push")))
+In addition to the event-driven programming model, Vaadin supports server push,
+where the UI changes are pushed directly from the server to the client without a
+client request or an event. This makes it possible to update UIs immediately
+from other threads and other UIs, without having to wait for a request. See
+<<dummy/../../../framework/advanced/advanced-push#advanced.push,"Server Push">>.
+
+Data Binding:: ((("Data
+Model")))
+((("Data
+Binding")))
+In addition to the user interface model, Vaadin provides a __data model__ for
+binding data presented in field components, such as text fields, check boxes and
+selection components, to a data source. Using the data model, the user interface
+components can update the application data directly, often without the need for
+any control code. All the field components in Vaadin use this data model
+internally, but any of them can be bound to a separate data source as well.
+((("SQL")))
+For example, you can bind a table component to an SQL query response. For a
+complete overview of the Vaadin Data Model, please refer to
+<<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding
+Components to Data">>.
+
+Client-Side Applications:: In addition to server-side web applications, Vaadin supports client-side
+application modules, which run in the browser. Client-side modules can use the
+same widgets, themes, and back-end services as server-side Vaadin applications.
+They are useful when you have a need for highly responsive UI logic, such as for
+games or for serving a large number of clients with possibly stateless
+server-side code, and for various other purposes, such as offering an off-line
+mode for server-side applications. Please see
+<<dummy/../../../framework/clientsideapp/clientsideapp-overview.asciidoc#clientsideapp.overview,"Client-Side
+Applications">> for further details.
+
+Back-end:: Vaadin is meant for building user interfaces, and it is recommended that other
+application layers should be kept separate from the UI. The business logic can
+run in the same servlet as the UI code, usually separated at least by a Java
+API, possibly as EJBs, or distributed to a remote back-end service. The data
+storage is usually distributed to a database management system, and is typically
+accessed through a persistence solution, such as JPA.
+
+
+
+
+