vaadin-framework/documentation/architecture/architecture-overview.asciidoc

---
title: Overview
order: 1
layout: page
---

[[architecture.overview]]
= Overview

Vaadin Framework 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[width=80%, scaledwidth=100%]

<<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 binding__ API for
associating data presented in field components, such as text fields, check boxes and
selection components, with a data source. Using data binding, the user interface
components can update the application data directly, often without the need for
any control code. For example, you can bind a data grid component to a backend query
response. For a complete overview of the data binding 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.