#1 OutSystems Global Partner in Customer Satisfaction according to OutSystems CSAT program.

Neo in Wonderland: a toolset to tune your OutSystems architecture and others stuff

by Fábio Fantato on Sep 03, 2018


Hello, my friends. I came back with a new article of ‘From Dusk Till Dawn’ series. If you missed them, see From Dusk Till Dawn (I): A Golden Buzzer of OutSystems´s Web Forge Components and leave your comments there.

(article originally published by our colleague Fábio Fantato on Medium)

This time I am going to share with you a toolset of components, methodology and patterns I always use for all projects in all steps of their development from analysis to delivery of OutSystems Projects.

My focus here will be on the architecture and maintenance side of things. So, I will cover:

  • How to design a good architecture before you start coding;
  • How to polish and validate your architecture;
  • The big picture of your app and data model;
  • Database maintenance tools;
  • Monitoring applications and contribution of each developer.



Note I will not cover the firsts steps of your project like getting the requirements and defining the execution plan and goals. I assume you already have done this.

But just in case you need some assistance I recommend you the book Lean Inception by Paulo Caroli. He shares how he has been doing the inception of his projects, through writing a product vision, capturing personas, understanding the user journeys, and developing high-level features.

The architecture design came just after this inception. I will go forward and leave you just at the point when you already know what you need to do (or you suppose to know) and you need to design your software and propose a good and scalable architecture to do it. It is not a secret to all IT professionals that well-thought-out architecture could be the difference between a projects´ success or failure. I´ll give you some tips to make the best architecture possible in the OutSystems ecosystem.


How to Design a Good Architecture before you start coding

There are a lot of frameworks, ideas or patterns in the market to support us in the creation of a good architecture and choosing one is hard and exhaustive job. The good news is OutSystems already did this job for us. They created a tool to make the design of architectures simple. More than a tool in fact OutSystems provides us a framework called 4 Layer Canvas or 4LC.


the 4 layer canvas


Using this framework you can promote the correct abstraction of reusable services including a microservices approach and the correct isolation of functional modules. This allows us real instead of so-called promise reuse capability when developing and maintaining applications in our infrastructures.

The methodology proposed by 4LC is similar to P.D.C.A. cycles (plan–do–check–act or plan–do–check–adjust), but here applies to a live and continuous process to disclose, organize and assemble the concepts and modules of your target application.


4LC will provide you with better architecture design, promotes a common understanding between business users and developers and enables easy validations of architectures. The main proposal is interact using those three phases of the picture above and classify them into one of four big layers.


4LC is a powerful tool to increase the quality of your architecture and it´s a good practice to keep your design live and updated during the entire lifecycle of the software.

To learn the details you can take these courses for web and mobile respectively:


https://www.outsystems.com/learn/courses/67/designing-apps-using-an-architecture-framework/ and https://www.outsystems.com/learn/courses/72/mobile-application-architecture/


There is also a useful forge component to help you design your architecture before starting your project.


electronic canvas


Using the Electronic Canvas you will be able to design your own architecture even before starting to code your application. Install it on your OutSystems environment and start using it. It is possible to export your diagrams to images using this Tool to include them into your project documentation.

sample project


How to Polish and Validate your Architecture

Perfect. Now I can start to code and I will never be back on the board to check my architecture, right? Wrong. After the initial design, you need to keep the architecture updated constantly. But how can you do this without a big project overhead. This is a million dollar question, but again I have good news. OutSystems has a tool to help you with this task.




Discovery is a featured component, i.e. it is a valuable component, not necessarily developed by OutSystems, that they believe most users will benefit from, either by direct usage, or by inspecting its content.

It allows you to create snapshots from your entire environment and analyse your modules and applications according to the rules proposed by the 4LC framework. By using Discovery you have a great tool at your disposal to analyse your architecture and check if your applications are using the best practices as proposed by 4LC framework, or whether they are violating them.

You can see a big picture of your environment and get some KPIs including information about cyclic dependencies,e.g. Module A usages Module B and Module B also usages Module A.

hive plot

All modules and applications available in your environment will be displayed here and you will be able to set the right layer they belong to. Discovery is not a magic tool, so you need to do this manually at first use.

After you map your modules, discovery gives you information about which elements (actions, screens, blocks and actions) are being used by consumers and producers, and whether you have violations of layer dependencies. For instance, a library module is not allowed to have dependencies from an end-user module.

asset manager

Discovery can show different views of information about your modules and their relationship.

internal modules



To learn more about how to use Discovery in your environment I suggest you watch the Validating and Refactoring Applications course available in the OutSystems Learn section. It will be a great starting point or keeping your architecture state-of-art. But don´t forget, you need to check your architecture regularly.



Big Picture of your app and data model

Now that you have your applications running well, you probably need a big picture of them to include in project documentation or even to share with your team. You can use the Clean Architecture Tool to help you with this task.


clean architecture tool


This component allows you to create a group of applications and set a list of exclusion and see your groups in a clean visual diagram. Clean Architecture has two perspectives of diagrams: One for applications and modules, where you can set if you want to group them by layers, show the extensions or not and define some other display rules.


The other view is to show your Entity-Relationship Diagram. But this is a simple diagram and does not include the entities’ attributes.



Database maintenance

In this section, I will show you 3 useful components I always use when I need to maintain my application database.




During the development we now our data model will change a lot to represent our real requirements. This has a side effect that will leave some garbage in the database that cannot be cleaned-up using the Service Studio or Service Center.

DBCleaner is a forge component, and while this tool is not supported it uses the DBCleanerApi available natively.

DBCleaner allows you to the physically delete old entities and attributes that aren’t used anymore. It is possible to remove old versions of modules, BPT process history logs and email logs too.

I am always run DBCleaner when I know my applications are stable and not subject to frequent changes anymore.


data extractor


Sometimes when you are using different environments (DEV, QA, Prod), there is a need to copy data between modules and applications or export them to test other environments using the same data in external systems.

The Data Extractor component allows you to extract scripts to recreate you entities in external databases and/or export your data in CSV format to be imported using using a bootstrap in other application you have.


sql map


When you are working with external systems, for instance, BI and/or ETL tools you need to map your queries to know the physical database names for each table you have in the query. OutSystems abstracts all table names when you are using them in Advanced Queries. E.g Entity User is the physical table OSSYS_USER.

SQL Map helps you to do this task. You can download and install it in your environment and it will translate your query to the physical names and vice versa.

logical physical


Monitor applications and contribution of each developer

Finally, my architecture was well designed, my database is clean and safe and my developers are doing their jobs (or are they?).




I am personally against strictly controlling the tasks or productivity of my developers, but the great value of this component is its nice comparison view where we can see who are the developers whom most contribute in my environment and which applications they are working on.

This component helps you to converts the boring auditing of their contributions into a game experience and on top of your board, you have only those guys who really deserve to be there.

In my opinion, this is the same concept as a daily scrum meeting. When people are sharing their contribution they are motivated to not look bad compared to the others.

Outgource also provides you with some visual information about which modules are receiving more contributions and how they are connected to each other.

list of applications

contributors portfolio



Is it all?

In fact, this is only the beginning. Keeping your architecture well-defined, clean and robust is a hard and perpetual job. There is always something to improve, fix or refactor. But you need to keep in mind, it is one of the most important stretches of time you should spend on your projects.

I didn´t cover the subjects in-depth so as not to be long-winded and boring. My thought here was giving you an insight and a starting point to help you successfully execute projects and write applications.

Next article from ‘From Dusk Till Dawn series’ will be focused on Mobile components. See you soon.



  • Share this article