Applications Architecture
Designing a Great Architecture
This lesson is part of the Planning your Application Architecture  course.

Hello and welcome to this session where I'm going to teach you how to build a
good architecture for your applications
in the OutSystems platform. After this session you will have
all the knowledge that you need for applications to be scaleable
highly performant and with a short footprint. Essentially
you'll know how to build great architectures. We're going to start by
why you should have a good architecture, after that
I will show you the tool that you use to build it. Next I will describe the
an the several steps involved and finally I'm going to explain to you
a few validation rules that you can use to guarantee that your architecture is
top notch.
Having a great architecture
is critical no matter in the technology that you are using because it represents
the earliest decisions in a project
which are usually the hardest to change an the most critical to get right.
By using a systematic approach that promotes reusability, abstraction and
you can structure your applications to be performance, reliable
and secure. When using the OutSystems platform this is no different:
having a good architecture paves the way to system success,
while having it wrong usually spells some form of disaster
and the unnecessary effort to recover from a wrongly started architecture
is much higher. Now, let's deep dive into building an OutSystems architecture.
The tool that we are going to use is called the OutSystems architecture
Typically this is something that we print and have on the wall next to each
and that is updated throughout the duration of the project. The architecture
has 4 layers on which you will conceptually place the modules that will
compose your application.
Each layer should contain modules according to a few well defined rules,
and we also have an area on top, where we place the roles
and the user stories for the system. Let's imagine that we are building a house
and we will do so from bottom to top. As such
let's look into our canvas the very same way. The bottom layer
which is called "Library Modules", is the layer where you will place the building
blocks of your application,
this is where you put everything that is common
and highly reusable, but does not have business logic
associated like, for example, user interface widgets,
themes, layouts or even exception handling. This is also the layer where you'll have the
connectors to external systems
or where you'll have wrappers to normalized API calls.
The second layer from the bottom is called
"Core Business" and it's where you will place reusable modules that
implement services around business concepts. This is also where you'll place
what we call
Core Entities, which are entities that represent core features around your
for example a product, and their associated details like, for example, the
product type.
These entities should be defined as public to be used by the upper layers,
but they should be set as read-only and you have to implement the APIs to allow
upper layer modules to change those entities. This is done
to give the modules on this layer the control over how the information is stored
on the database regardless of the source. On this layer
you can have user interfaces but not for the end user.
Usually you will have back offices to manage the core
entities' information, for example, a back office to manage the products.
Also on this layer you can have assynchronous data processing
and roles specific to access the features implemented on his layer.
The third layer is called "End User"
and this is where you place the modules that implement user interfaces to
support the use cases of the application.
This is also where you will place the business logic that cannot be isolated
on the Core layer,
and also when where the workflows to orchestrate the use cases are also placed.
You can have entities at this level
when they exist to extend the core entities, like, for example,
a line item where you could relate a product with a purchase order.
Finally the upper layer it's called "Orchestration"
this is where you place the modules that orchestrate the user interface
and perform usability optimizations based on the user's
role. A typical example is like when you have an internet portal
that orchestrates the access to other internal applications
based on the employee role. So now that we know the tool
let's talk about the process. The process that we are going to use
is an iterative one, where you'll keep repeating three steps until you have your architecture
The first step is called "Disclose":
this is when you'll identify the needs for your application.
First, you'll need to identify the business roles involved
to understand where they might fit. You will also need to identify the user stories
for each role
in order to understand the new processes or change the existing ones:
basically you want to know who is going to do what
and why. Next, you will identify the information architecture according to each business
this will allow you to understand the navigation patterns
and how they will match the user expectations. After that,
you will identify the integration needs for the application
what are the external systems that we will have to integrate with
and how. This will allow you to understand some unknown features of the
external technology
and what we will need to do to cope with that. Finally,
we will need to understand if there are specific user experience needs like
for instance
visual requirements or accessibility needs for the users.
So now let's see how we can start building an architecture
with an example. In this example we are going to build an application to the
Retail Inc. company
which has over 100 stores and sells thousands of products from
hundreds of suppliers. We also know that their quality department wants to
automate three existing processes:
the "Product Recall" and two other processes
which are called the "Supplier Audit" and the "Store Audit".
We know that the product recall process exits to recalled products or product
families from the stores, that were stocked by a specific supplier.
This can happen, for instance, if the products are wrongly labeled
or for food safety reasons. The process starts with the recall executives
selecting the stores from which the products will be recalled, which are then notified.
After that, the store manager does a report on the existing stocks
which is then communicated to the supplier that prepares and suggests a
plan for the recall.
After the plan is validated by the recall executive,
the store managers start the execution of that same plan.
Finally we are informed that the suppliers are managed by an external
Based on this information
what have we identified? For integrations, we know that we will need to integrate
with an external ERP system and, for that, we will need to build some kind of connector
to communicate with that system.
We also identify the few business concepts, like product,
supplier stock or store. For user interfaces we know that we'll have a
which is the recall process, and that we'll also have a few user
interfaces to support that same process.
In terms of access portal, so far we don't have any information.
So let's move into the second step which is called
"Organize". This is when you'll place the concepts identified in the architecture
on the layer identified, but remember: this is an iterative process
and we'll continue to repeat it. Now into the canvas.
First, we identify the few roles
these are not part of the layers, but should be on the canvas so that we know
who is going to use the application. The ERP connector,
as an highly reusable component, that allows connection to an external
system, should be placed
on the Library layer. Now the Core Business concepts that we have
these will be placed on the Core Business layer. And the user interfaces and the
processes that we have any defined as well
will be placed on the End User layer. The audit starts by doing an hazzard
followed by a check of the critical control points. After that, the supplier
is awarded a classification, and if the score's below 50
he's excluded from the chain. if the score's below 70,
a new audit will be done in six month, and if the score is below 90
a new audit is done only next year. The process starts with the supplier
auditor going into the supplier facilities and perform an audit
according to the rules. He or she then
elaborates a report, sends it to the supplier and plans for the next audit.
Finally, the supplier checks the report and follows the necessary
now that we have identified a few more concepts, let's move into the canvas
We identify the new role, which is the supplier
auditor, and we have also identified a few other business concepts,
like the supplier audit, the supply report and the supplier
audit plan. Finally, we have identified some more user interfaces
which will be required for the supplier audit process.
Let's do one more iteration now with a third process,
the store audit. This process is very similar to the previous
and is executed to audit the stores once every six months to verify the storage
the staff working conditions and the materials used. We are also informed that
the auditors
will be drafted by region manager for each region. The process starts with a
store auditor going into the stores and performing an audit according to the
He or she then elaborates a report, sends it to the store manager
and plans for the next audit. The store manager then checks the report
and follows the necessary recommendations. So,
you know the drill by now: we have identified two new roles,
the store auditor and the region managed. We have identified a few new
business concepts, like store audit,
report and audit plan, as well as location because of the regions.
We know that we will need other user interfaces to support the store audit
To finalize, we are informed by the customer that we will need three
different access portals:
one to be used by the back office users, one for the internal business users
and finally one for the external partners. As you can see the requirement is that the
have different look-and-feels and are targeted at different roles.
So now again in our canvas we know now that we will need
three themes to support each of the portals. This theme should be placed on
the Library layer.
We also know that we will have three portals that should be placed on the
Orchestration layer.
The first two steps are done
so let's move into the third. The final step is called
"Assemble". This is where you will use the set of rules, patterns and
recommendations to consolidate your modules in the canvas.
You will do this to have your modules organized in a way to simplify the
and also to guarantee that you don't have duplicated logic or information.
So by analyzing our canvas the first thing that we see are those modules
identified as Core
but that that really attached to a specific process,
like for instance the store audit in report modules
which are part of the store audit processes and the same can be said for
the supplier audit
and the recall plan modules. These modules should be placed next to the
corresponding process.
Continuing our analysis
we need also to understand which concepts can live by themselves or not.
In our example, the product and product family
cannot be separated: if you think about it, a product family on its own
doesn't make sense because it's a characteristic of the product
and therefore should be next to it.
Finally, we have the other reusable core concepts
that should be exposed as services to be reused by this
and future systems. We now have all modules in the canvas
organized and place on the correct layers and this is the final result of our
architecture exercise. So now that we have an architecture
let's learn a few validation rules that we must enforce to guarantee that
we have a great architecture.
The first and most important one is
no upward references! This means that the module on a low layer
can never, ever reference a module from an upper layer. Why?
Let's imagine that we have this architecture where we have two End User
modules that reference two Core modules
that, in turn, reference a Library module. If we create a reference between the
Library module
and End User module, we will create a cluster of dependencies
between all these modules. The second rule says
that you cannot have side references among modules
on the Orchestration or End User layer.
Let's take a slightly different example, where we have two End User
each referencing different Core or Library modules.
If you add a reference between the first End User module
and the second, you will unnecessarily create
an inheritance between the first module and the dependencies
of the second. The third rule says that on the Core and Library layers
you can have side references, but you need to make sure that in doing so
you don't create any cyclic dependencies. You need to do this by paying special
attention to how the models are related to each other.
The fourth rule says that in the Core Business layer you cannot have front-end
and that your entities should be exposed as read-only,
but like I said previously, you can however have back office screens to
manage those same
entities. The fifth rules says that in the Library layer
you cannot have business logic nor role-based logic.
This is done because in this layer you should have those
highly reusable components which are agnostic from the business rules
and that could be used by any application like, for example,
and SAP connector. Here you have a cheat sheet of the rules:
you should have all these in mind and try to enforce them all, but you have to
prioritize them
do so by reading them from top to bottom. By applying these rules
you will guarantee that you have a sane and flexible architecture
that will decrease significantly the footprint of your application
thus simplifying the maintenace, refactoring and deployment times.
So far we've been talking about modules but, as you know
with the OutSystems platform you usually deal with applications
so, what about them? As you know, one application is a container of modules
that can be
extension modules or the eSpace modules, and you can create
references between eSpace modules and modules of either type.
In this example let's say that the directory module, which is part of the
directory application, references
the binary data extension module, which is part of the system components
and also the employees eSpace module from the intranet services application.
By referencing
these modules, you will create a dependency between the applications
where they are contained
and as your applications grow and grow with more modules and become
you may ask yourself "what about my architecture now"?
The good news is that you already know
everything there is to know even for applications, you just have to take a few
other things into consideration.
Let's say that we have four applications, each with different modules that span
all the layers. In such scenario, the obligations should be classified
according to the module that's on the highest layer. So for the first
application the highest model
is on the Core layer and therefore is considered
Core Business application. For the second application,
the highest model is on the End User and therefore is considered a End User
For the third, because the highest module is on the Orchestration level,
is considered an Orchestration application. And finally, for the fourth
application, all modules are at the same layer
so it's considered a Library application. Knowing this,
you can now go back into the canvas, place your applications in the appropriate
and apply the same validation rules you already know. So now that you know how to
build your OutSystems architecture,
remember that this is an ongoing job and as new concepts appear
your applications evolve and so will your architecture. Use the canvas to help you
on architecture or re-architecture activities,
keep iterating through the three steps until you have an architecture
and remember to always apply the validation rules to make sure that you
have the most solid
and flexible architecture possible. This concludes our session,
thank you very much.