:toc: macro
toc::[]
:idprefix:
:idseparator: -

= Architecture

There are many different views that are summarized by the term _architecture_. First, we will introduce the xref:key-principles[key principles] and xref:architecture-principles[architecture principles] of devonfw. Then, we will go into details of the the xref:application-architecture[architecture of an application].

== Key Principles
For devonfw we follow these fundamental key principles for all decisions about architecture, design, or choosing standards, libraries, and frameworks:

* *KISS* +
Keep it small and simple
* *Open* +
Commitment to open standards and solutions (no required dependencies to commercial or vendor-specific standards or solutions)
* *Patterns* +
We concentrate on providing patterns, best-practices and examples rather than writing framework code.
* *Solid* +
We pick solutions that are established and have been proven to be solid and robust in real-live (business) projects.

== Architecture Principles
Additionally we define the following principles that our architecture is based on:

* *Component Oriented Design* +
We follow a strictly component oriented design to address the following sub-principles:
** http://en.wikipedia.org/wiki/Separation_of_concerns[Separation of Concerns]
** http://en.wikipedia.org/wiki/Reusability[Reusability] and avoiding http://en.wikipedia.org/wiki/Redundant_code[redundant code]
** http://en.wikipedia.org/wiki/Information_hiding[Information Hiding] via component API and its exchangeable implementation treated as secret.
** _Design by Contract_ for self-contained, descriptive, and stable component APIs.
** xref:technical-architecture[Layering] as well as separation of business logic from technical code for better maintenance.
** _Data Sovereignty_ (and _high cohesion with low coupling_) says that a component is responsible for its data and changes to this data shall only happen via the component. Otherwise, maintenance problems will arise to ensure that data remains consistent. Therefore, interfaces of a component that may be used by other components are designed _call-by-value_ and not _call-by-reference_.
* *Homogeneity* +
Solve similar problems in similar ways and establish a uniform link:coding-conventions[code-style].

As an architect you should be prepared for the future by reading the https://www.capgemini.com/de-de/wp-content/uploads/sites/5/2020/07/TechnoVision-2020-Report.pdf[TechnoVision].

== Application Architecture

For the architecture of an application we distinguish the following views:

* The xref:business-architecture[Business Architecture] describes an application from the business perspective. It divides the application into business components and with full abstraction of technical aspects.
* The xref:technical-architecture[Technical Architecture] describes an application from the technical implementation perspective. It divides the application into technical layers and defines which technical products and frameworks are used to support these layers.
* The Infrastructure Architecture describes an application from the operational infrastructure perspective. It defines the nodes used to run the application including clustering, load-balancing and networking. This view is not explored further in this guide.

=== Business Architecture
The _business architecture_ divides the application into _business components_. A business component has a well-defined responsibility that it encapsulates. All aspects related to that responsibility have to be implemented within that business component. Further, the business architecture defines the dependencies between the business components. These dependencies need to be free of cycles. A business component exports its functionality via well-defined interfaces as a self-contained API. A business component may use another business component via its API and compliant with the dependencies defined by the business architecture.

As the business domain and logic of an application can be totally different, the devonfw can not define a standardized business architecture. Depending on the business domain it has to be defined from scratch or from a domain reference architecture template. For very small systems it may be suitable to define just a single business component containing all the code.

=== Technical Architecture
The _technical architecture_ divides the application into technical _layers_ based on the http://en.wikipedia.org/wiki/Multilayered_architecture[multilayered architecture]. A layer is a unit of code with the same category such as a service or presentation logic. So, a layer is often supported by a technical framework. Each business component can therefore be split into _component parts_ for each layer. However, a business component may not have component parts for every layer (e.g. only a presentation part that utilized logic from other components).

An overview of the technical reference architecture of the devonfw is given by xref:img-t-architecture[figure "Technical Reference Architecture"].
It defines the following layers visualized as horizontal boxes:

* link:guide-client-layer[client layer] for the front-end (GUI).
* link:guide-service-layer[service layer] for the services used to expose functionality of the
back-end to the client or other consumers.
* link:guide-batch-layer[batch layer] for exposing functionality in batch-processes (e.g. mass imports).
* link:guide-logic-layer[logic layer] for the business logic.
* link:guide-dataaccess-layer[dataaccess layer] for the data access, especially persistence.

Also, you can see the (business) components as vertical boxes (e.g. _A_ and _X_) and how they are composed out of component parts each one assigned to one of the technical layers.

Further, there are technical components for cross-cutting aspects grouped by the gray box on the left. Here is a complete list:

* link:guide-security[Security]
* link:guide-logging[Logging]
* link:guide-monitoring[Monitoring]
* link:guide-transactions[Transaction-Handling]
* link:guide-exceptions[Exception-Handling]
* link:guide-i18n[Internationalization]
* link:guide-dependency-injection[Dependency-Injection]

[[img-t-architecture]]
.Technical Reference Architecture
image::images/T-Architecture.png["devonfw architecture blueprint",scaledwidth="80%",align="center",link="https://devonfw.com/website/pages/docs/images/T-Architecture.svg"]

Please click on the architecture image to open it as SVG and click on the layers and cross-cutting topics to open the according documentation guide.

We reflect this architecture in our code as described in our link:coding-conventions#packages[coding conventions] allowing a traceability of business components, use-cases, layers, etc. into the code and giving
developers a sound orientation within the project.

Further, the architecture diagram shows the allowed dependencies illustrated by the dark green connectors.
Within a business component a component part can call the next component part on the layer directly below via a dependency on its API (vertical connectors).
While this is natural and obvious, it is generally forbidden to have dependencies upwards the layers
or to skip a layer by a direct dependency on a component part two or more layers below.
The general dependencies allowed between business components are defined by the xref:business-architecture[business architecture].
In our reference architecture diagram we assume that the business component `A1` is allowed to depend
on component `A2`. Therefore, a use-case within the logic component part of `A1` is allowed to call a
use-case from `A2` via a dependency on the component API. The same applies for dialogs on the client layer.
This is illustrated by the horizontal connectors. Please note that link:guide-jpa#entity[persistence entities] are part of the API of the data-access component part so only the logic component part of the same
business component may depend on them.

The technical architecture has to address non-functional requirements:

* *scalability* +
is established by keeping state in the client and making the server state-less (except for login session). Via load-balancers new server nodes can be added to improve performance (horizontal scaling).
* *availability* and *reliability* +
are addressed by clustering with redundant nodes avoiding any single-point-of failure. If one node fails the system is still available. Further, the software has to be robust so there are no dead-locks or other bad effects that can make the system unavailable or not reliable.
* *security* +
is archived in the devonfw by the right templates and best-practices that avoid vulnerabilities. See link:guide-security[security guidelines] for further details.
* *performance* +
is obtained by choosing the right products and proper configurations. While the actual implementation of the application matters for performance a proper design is important as it is the key to allow performance-optimizations (see e.g. link:guide-caching[caching]).

==== Technology Stack
The technology stack of the devonfw is illustrated by the following table.

.Technology Stack of devonfw
[options="header"]
|=======================
|*Topic*|*Detail*|*Standard*|*Suggested implementation*
|runtime|language & VM|Java|Oracle JDK
|runtime|servlet-container|JEE|http://tomcat.apache.org/[tomcat]
|link:guide-dependency-injection[component management]|dependency injection|https://jcp.org/en/jsr/detail?id=330[JSR330] & https://jcp.org/en/jsr/detail?id=250[JSR250]|http://spring.io/[spring]
|link:guide-configuration[configuration]|framework|-|http://projects.spring.io/spring-boot/[spring-boot]
|link:guide-dataaccess-layer[dataaccess] (persistence)|OR-mapper|http://www.oracle.com/technetwork/java/javaee/tech/persistence-jsp-140049.html[JPA] | http://hibernate.org/orm/[hibernate]
|link:guide-batch-layer[batch]|framework|https://jcp.org/en/jsr/detail?id=352[JSR352]|http://projects.spring.io/spring-batch/[spring-batch]
|link:guide-service-layer[service]|link:guide-soap[SOAP services]|https://jcp.org/en/jsr/detail?id=224[JAX-WS]|http://cxf.apache.org/[CXF]
|link:guide-service-layer[service]|link:guide-rest[REST services]|https://jax-rs-spec.java.net/[JAX-RS]| http://cxf.apache.org/[CXF]
|link:guide-logging[logging]|framework|http://www.slf4j.org/[slf4j]|http://logback.qos.ch/[logback]
|link:guide-validation[validation]|framework|http://beanvalidation.org/[beanvalidation/JSR303]|http://hibernate.org/validator/[hibernate-validator]
|link:guide-security[security]|Authentication & Authorization|http://www.oracle.com/technetwork/java/javase/jaas/index.html[JAAS]|http://projects.spring.io/spring-security/[spring-security]
|link:guide-monitoring[monitoring]|framework|http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html[JMX]|http://spring.io/[spring]
|link:guide-monitoring[monitoring]|HTTP Bridge|HTTP & JSON|http://www.jolokia.org[jolokia]
|link:guide-aop[AOP]|framework|http://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Proxy.html[dynamic proxies]|http://docs.spring.io/autorepo/docs/spring/3.0.6.RELEASE/spring-framework-reference/html/aop.html[spring AOP]
|=======================