Skip to main content

Front-end Architecture

· 11 min read
Bruno Carneiro
Bruno Carneiro
Fundador da @TautornTech

This is an article I've wanted to write for a long time but kept putting off... Today I woke up at 5am and, by some hidden force of nature, sat down in front of the PC to write something mysterious that came out of my head.

Without further ado, the goal here is to describe some Front-end architectures — a complex and strangely underaddressed topic.

In this article I'll cover an example of architecture and the traps of not following a well-defined pattern. What I bring is the software developer's perspective and things they should care about to mitigate future problems, for themselves and for the company.

Software architecture is about what matters to the business.


First of all, I want to share a tweet (I know it's called X now, but it's a terrible name and hard to make sense of — it sounds like a different site...) that I found in this article which I thought was fantastic.

D-e-f-i-n-i-t-e-l-y folder structure is NOT software architecture — not yesterday, not today, and it won't be tomorrow either. If you say you organized some folders and that's your architecture, you are completely mistaken.

BUT, in fact there is a correlation: folder structure is very important because it says a lot about the organization of your system and the relationship between structures, rules, and patterns. It creates scope and logic at different levels to actually have a decent structure for development, finding files, and evolving things.

This is undoubtedly one of the most common failures. The first is not knowing what architecture to use (when you don't mix several out of pure hype), and the second for me is organizing the project poorly.

I've worked on several systems with well-defined architectures — on paper — but that in practice scaled in a disorganized way. What you find most on the internet is that Clean Architecture with few cases where the system starts to scale and everything falls apart because scale (as a team) wasn't thought through, and most people didn't actually understand what each proposed layer does.

This isn't a criticism of Clean Architecture (I'm not crazy, and what can I say about Uncle Bob — simply one of the greatest geniuses in programming). The criticism here is for those who use it without knowing how. The proposed format works very well when properly applied.

But to get straight to the point, one of the biggest problems I see is the lack of knowledge about what each architecture proposes as a solution, how it's organized, and whether you/your team/your project actually need it.

How about a microservice for a login page? hehehe

But where does Front-end come in? A problem I see is the lack of knowledge about the existing architectures for solving Front-end problems and the ability to scale libraries (there's a new one every day solving something in a miraculous way).

Knowing software architecture in general is the foundation for everything. The good and bad decisions you make affect not just you, but your team, project, and users. Think about that before adding the latest trendy lib.

What is software architecture?​

Well, as I said, architecture is not about folder organization (even though that is very important). It's about the important decisions you make at the beginning of a project.

"Architecture is about the important stuff. Whatever that is". Martin Fowler

Whenever I'm asked about architecture I recommend this article, young grasshopper: Martin Fowler

I have another article I wrote, in general terms, about software architecture.

::: info A lot of what I could say here is covered in the article I mentioned earlier, and to avoid being repetitive I'll focus on Front-end. For what I actually believe architecture is, what it isn't, and other aspects, I recommend reading my article first. :::

How to think about an architecture?​

Whenever I'm starting a software architecture, I like to question the needs of the product/project I'm developing. That is the basis of the project's needs — the opposite is just a pile of technology and personal taste.

Here are some important points to question:

  • Who is the audience that will use the application?
  • What are the business priorities?
  • Does it need to be mobile-first?
  • Does it need to work offline?
  • Are there existing APIs we need to connect to? I'm imagining a scenario where orchestrating requests from multiple modules is necessary.
  • Is the Front-end responsible for multiple calls? This ties into the previous point — it's to understand if an Edge API layer is even necessary.
  • What level of optimization is needed? Imagine needing to run on low-performance devices, then optimization (which is always important) may be one of the key points.
  • Available cost and budget. This is quite important because it can limit access to certain technologies, requiring internal development or the use of cheaper or similar resources. Not every company will be able to pay for an observability platform that costs $10k, for example.
  • Are there existing FE modules that need to be coupled to the new project while keeping evolution separate? Think about internal npm packages or even microfrontends.
  • User traffic (thinking about page and module load times, as well as feedback for the user).
  • Still thinking about the previous point, this can lead to another question. Does the platform need to work both synchronously and asynchronously? It's very common for requirements to come with these specifications, but there may be scenarios where we need to think about this from the start.
  • Is a caching system on the Client needed?
  • Is a Storage system on the Client needed?
  • Development flow and release distribution
  • Testing model (unit, integration, e2e).
  • CI/CD
  • Delivery and release rollback
  • Observability
  • Number of people who will work on the project. There can be small and even mixed teams working on the same solution, and this directly impacts deliveries and system evolution.
  • Is a design system needed? (be careful with this item — it might seem interesting but can also become a major headache)
  • Development of team guidelines.
  • Security level
  • Scalability
  • Reusability
  • Is there any notification system?
  • Is a BFF or orchestration system needed?
  • Documentation
  • Third-party dependencies
info

Have you heard of Functional and Non-Functional Requirements? [English version] Knowing about functional and non-functional requirements is a way to guide yourself through the topics mentioned above.

There are some other points, but the main idea here is: BE ALIGNED WITH THE BUSINESS. And what I listed above is valid for a Software — I'm not thinking specifically about Front-end or Back-end, but about a Software where there are layers and various points to consider.

That said, it's normal that not everything desired by the technical team will be possible to implement.

Problems that can occur​

As you may have noticed, this is basically a non-functional requirements gathering exercise. Of course the focus is on the system (functional requirements), but knowing this gives us what the architecture needs to have.

I listed many items here — and that list can grow — that are very important, but don't necessarily need to be there from the start. Many of them shouldn't exist initially because it can lead to a well-known problem called overengineering. Which is basically too much technology to solve a specific problem when something simpler could have worked.

Imagine using a bazooka to kill an ant. It makes no sense at all. But this happens frequently. 🐛

A classic example: the system is still in MVP, the team doesn't even know if it will scale or whether there will be users. But a system was created with microservices, microfrontend, with several design patterns overriding each other. Clean Architecture mixed with Hexagonal, and so on...

On the Front-End, there's Relay with a Storage system to control pages and tabs, components built with Atomic Design, and a structure that resembles Next.js with hundreds of custom hooks scattered around, one for each API call.

Total chaos.

Thus creating a slow, expensive MVP with few tests to know if it actually has market fit. Only after that should the team gather requirements to actually meet the system's needs.

Front-end Architecture​

Alright, but given all those points raised, how should I build the Front-end architecture and what options exist?

Let me list some:

Component-Based Architectures​

Most modern frameworks (React, Vue, Angular, Svelte) adopt this model:

  • Atomic Design: Organization of components into atoms, molecules, organisms, templates, and pages
  • Design System: Unified system of components, tokens, and patterns
  • Component Libraries: Collections of reusable and consistent components

Data Flow Architectures​

  • Flux/Redux: Centralized store, actions and reducers
  • MVC/MVVM: Separation between model, view, and controller/view-model
  • Clean Architecture: Separation by responsibility layers
  • Hexagonal/Ports & Adapters: Isolation of the application Core
  • Feature Sliced Design (FSD): An architectural methodology for front-end projects that organizes code into layers (slices) based on business features.
  • Signals (Angular, Solid, Vue): Reactive system based on observable primitives
  • Context API (React): Lightweight alternative to Redux for state management
  • Zustand/Jotai/Recoil: State libraries that offer simpler approaches
  • Event-Driven Architecture: Based on events and listeners for communication between components

Scale Architectures​

  • Micro-frontends: Splitting the front-end into independent applications
  • Module Federation: Code sharing at runtime
  • Monorepos: Organization of multiple packages in a single repository
  • Jamstack: Combines JavaScript, APIs, and pre-rendered Markup for better performance

Choosing the appropriate architecture depends on the size, complexity, and requirements of your application.

A tangled web of architectures and project setups has emerged here, and since I gave only a brief explanation of each, things may have become more confusing. But I wanted to show the diversity and variety of project organizations — understanding each one is necessary to know which is most appropriate for each project.

Even so, some are more common in the market, such as MVVM patterns, Flux/Redux/Zustand, Design System, Feature Sliced Design...

There are other approaches, but I won't cover them all — even if I wanted to, I don't know all of them hahaha.

But it's important to understand the strengths and weaknesses of each one — it's a tradeoff between different trade-offs.

How I like to build my projects​

Folder structure and application design is an extremely important topic for the development of websites and applications. I see many people with no idea how to create a good software architecture — this mainly happens with those working in Front-end development.

I bring here an architecture I've been working with for many years and that is in fact efficient and scalable. Of course, it's normal to make adaptations for some projects, and it's not a silver bullet — it also has requirements and disadvantages. But it has worked very well for most projects I've worked on.

Larger projects with hundreds of teams may require a different model, such as monorepo, microfrontend, and a distributed design system. But that's not the case for most companies. Therefore, what I bring below is quite robust:

src/
├── pages/
│   └── knowledge/
│       ├── index.tsx
│       ├── __tests__/
│       │   └── knowledge.test.tsx
│       ├── interfaces.ts
│       ├── knowledge.tsx
│       ├── action-bar.tsx
│       ├── menu.tsx
│       └── utils.ts
├── routes/
│   ├── auth.ts
│   ├── main.ts
│   ├── private.ts
│   ├── index.ts
├── components/
│   ├── card/
│   ├── button/
│   ├── wallet/
│   └── index.tsx
├── providers/
│   ├── main-provider.ts
├── templates/
│   ├── main.tsx
│   ├── index.tsx
├── hooks/
├── types/
│   ├── module.d.ts
│   └── inference.d.ts
├── commons/
│   ├── i18n/
│   ├── utils/
│   ├── constants/
│   ├── config/
│   ├── react-query/
│   └── styles/
│       └── global.css
├── assets/
│   ├── administration.svg
│   └── spin.svg
├── resources/
│   ├── client/
│   │   ├── knowledge.ts 
│   │   ├── cortex.ts
│   │   └── supabase.ts
│   └── api/
│       ├── benchmarks/
│       │   ├── contract.ts
│       │   ├── index.ts
│       │   └── services.ts

There are several levels, and it may be difficult to capture in detail based on this structure, but I'll try to explain in the best way I can:

I divide the architecture into a few modules

assets​

Nothing too mysterious — images and fonts go here, basically.

commons​

This folder has subdivisions.

components​

hooks​

pages​

providers​

resources​

routes​

templates​

types​

References:​