5 Atomic Rules for Starting Your Scalable
Front-End Architecture
Do you remember when you were a kid and got a new toy for your birthday? I bet it took you about two minutes to start playing with it!
Why? Because the company who made it was clever enough to build it using recognizable patterns that would make it easy to start playing with it in no time. Now, imagine you get a toy that, before you can start playing with it, you have to build it and then learn a completely new way to interact with it. Maybe a few of you would love that kind of approach, but I assure you that most people don’t have that kind of patience.
The same can be said about the appliances, cars, mobile devices, and gadgets that make lives easier for adults. We like them because it doesn’t take us long to start using them.
The Problem
At this point, you might be wondering what this introduction has to do with front-end architecture. Well, if we all understand, from a tender age, that reinventing the wheel is frustrating and goes against our natures, then it becomes easier to question why most developers start a project with a blank canvas approach every single time. Why go against human nature?
Before I came to OutSystems, I saw a lot of projects canceled in the first two weeks. The most common reason for that was "We are already two weeks into the project, and there is nothing to show."
The people who said this were unaware of the database, core methods, and authentication efforts—those painful and highly important things that ensure a good base for every project. As a result, they thought nothing had been done—or at least nothing that produced a minimal viable product.
So what can we do to avoid this painful, error-prone process of reinventing the wheel every single time?
The Solution
Well, I’ve already hinted at the answer, so no surprise here (M. Night Shyamalan, if you are reading this, I’m sorry for the disappointing storyline; I promise I’ll try a better plot twist next time). Yes, that’s right: it’s to build these modules and classes ahead, thereby accelerating the process.
Although this can be applied to every facet of development, I will just focus on the front-end. I’m going to show you how you can get rid of all the dumb work you have to do over and over again so you can focus on those little things that really add value to your project. The ones that take it from good enough to something outstanding.
And you know what else? What I’m about to tell you will also:
- Most likely decrease the final effort of the project.
- Preserve your sanity while developing.
- Be maintenance friendly and scalable for the future.
Most importantly, there is a high probability that everyone will be happier in the end, and who knows, maybe there will be a dinner, a lot of drinking, and an exchange of praises and hugs (in this specific order).
So, how can you achieve this? Here are five basic rules that, if well applied, are a good starting point for a scalable front-end architecture.

My goal is not to say which conventions and nomenclatures you should follow. I’m much more focused on organization and mindset. I believe that you will figure out, on your own, the procedure that best suits your project or company, whether that’s BEM, SMACSS, OOCSS, or another modular architecture approach.
The suggestion here is just to adapt the rules into your ecosystem in the way that works better for you. If your ecosystem involves OutSystems, I will also tell you how these 5 rules can be applied in our world.
1. Define the HTML Layout Structure as a Skeleton and Start to Work From It
A good foundation is essential for success. That is why you must invest in creating the best foundation possible. To achieve this:
- Avoid the proliferation of different layout structures. You should reduce them to a minimum. A new layout structure only makes sense if the value of the necessary changes is obvious and focused on the business goal needs. Maintain a few good layout structures; it’s the right thing to do for low maintenance and good scalability.
- Take care of the backbone. In a typical structure, you must start by building the first level of boxes, the outlines, the basic structure, the place to fill the header, menu, footer, and container. The actual data inside (for example, the menu itself) and the style are a different story; don't think about them at this point.

2. Control Your CSS Base
For CSS, I recommend that you apply the method that suits your needs better and ensure that everyone on your team follows your direction. However, here are a couple of things to keep in mind.
- Create Your Own Reset Styles. Commonly known as reset.css, this does not need to be an independent file (which will consume an extra resource). It just needs to be your starting point CSS file with your baseline rules, so you can work on top of that in your projects. With this approach, you will decrease browser incoherence about element properties (each browser has its own set of rules), and you will format the elements you want. This will be helpful because all developers will know the baseline and can dispense with thinking in exceptions like “p,” “h1,” etc.

- Be Careful With the Use of Preprocessors. You can use preprocessors like SASS and LESS to help you achieve this and other rules you want to apply in your CSS. But, you should use them with caution and avoid them if you don’t fully understand nesting and mixing; otherwise, you can end up with a bunch of garbage.
I know a lot of people who use these preprocessors because of the variables that can be applied and to speed development and maintenance. But, really, it’s overkill. And, you don’t really need it because you can use CSS variables after chrome 49 with function var().
Also, I’m pretty sure that CSS custom properties are the future (if not already the present), so this is definitely the time to become expert on the subject.
3. Use Patterns
A pattern is a reusable modular block that solves most common scenarios, and it defines a standard structure (for example, datepicker, range slider, dropdown, panel). You can achieve this with a lot of methods like MVC, but the most famous one is HTML5 Web Components.

You should use these blocks as much as possible because they speed up development and maintenance by:
- Centralizing structure and functional code. With them, when you change something, it will be applied everywhere that the pattern is used, increasing productivity and decreasing maintenance.
- Not adding business logic to them. Functional logic is all you need for the proper working of the structure of these patterns. Without business logic, they can be reused more often, applied in different scenarios, and even used in different applications.
- Extending your patterns instead of cloning them. Use pseudo elements to avoid rewriting a specific structure and to keep garbage out of it. If you need the structure in one scenario and not in others (for example, different applications), use the CSS "::before" and "::after" selectors to add a new element.
4. Define Your Own Rules and Processes for Scalability
Many teams have difficulty defining processes. If you struggle in this area, my recommendation is to try to understand your team’s and your organization’s needs. If you do that, you will find the right answers to solve your problems. It is important to have a set of rules, no matter what type of methodology you are using. Here’s how to put your set together.
- Designate Your Team's Main Goal. This will set the tone for the team, ensuring that everyone is on the same page. Also, the steps the team must take to achieve this goal are visible.
- Define a Strategy and Dynamics. Achieving your goal is easier if you have a good set of dynamics and processes that the team shares. Define everything your team needs to be successful, such as the analysis process, backlog process, task development checklist, and the test checklist.
- Create Processes That Support and Protect Sanity. Your responsibility doesn’t end with what relates to your team directly if you are involved in a process that goes through several teams. So, make sure you are part of the overall success. This means being proactive whenever there are challenges in the handovers between teams, such as the process between UX -> UI -> front-end -> back-end teams. At the same times, have well-established limits on what’s your responsibility, deliverables, and inputs. This will prevent lots of "oh, I was thinking you were going to do that" moments.
- Create a Single Channel of Input and Information. This can be a person or a tool (most of the time, it’s both). What’s important here is that everyone should know how to interact with your team officially for things like making a request or reporting a bug.
In addition, communication from your team to the outside world should also be clear and efficient, letting everyone know what you are doing. Examples include sending a periodic email, scheduling handovers and brown bags, and building a live style guide.
As for technical stuff, and since this will be your daily communication with other teams (the real output of your teamwork), your architecture should always be based on a set of rules and conventions that everyone should follow to avoid misunderstanding. It can be Web Components, Inuitcss, BEM, SMACSS, OOCSS, or even your own personal methodology. Once again, choose the one that suits your needs best. The goal is to have everyone on the same page about those rules and about when and how to apply them. In my experience, you know you were successful when all the output appears to be coming from the same person.
5. Create a Platform to Centralize all Information
This is all fine and dandy, but even with this set of rules, it is easy to get lost in a project because we just can’t store everything in our brains. Therefore you should create a centralized single source of truth. It is very helpful to create a place, called a live style guide, that can work as a central point where you document your rules.
The live style guide is all about consistency. Isolate all the components to evolve them easily, and document the visual language and branding applied to the different UI patterns and elements.
It should be your bible. A place where developers can check how patterns should look and see live examples of those components all together in a single spot. Also, all component evolution and major changes should be applied in the live style guide to assure the centralization that makes maintenance easier.

Joining the Atoms and Creating Molecules
If you apply these five rules, I promise that your deliverables will increase. You will have more time to focus on the little details that will make a difference instead of having to recreate the wheel painstakingly. This article shows what a comfort it can be to have a sound structure already created; you’ll also see how much you can accelerate your development.
In the articles to come, we will cover these rules in more detail. I will show you how to connect all the dots without losing your mind and how OutSystems can help you accelerate all these practices by providing out-of-the-box accelerators that will enable you to start a project even further ahead.