Category: Architecture

Documenting Software Architecture

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

We learn how to code and we build some cool applications, and then we learn about architecture and how to make the application maintainable for several years…

However when we need to explain to someone else (new developer, product owner, investor, …) how the application works, we need something more… we need documentation.

But what documentation options do we have that can express the whole application building blocks and how it works?!

In this post I’m going to write about:

  • UML
  • 4+1 Architectural view model
  • Architecture Decision Records
  • The C4 Model
  • Dependency diagrams
  • Application Map
Continue reading “Documenting Software Architecture” →

Reflecting architecture and domain in code

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

When creating an application, the easy part is to build something that works. To build something that has performance despite handling a massive load of data, that is a bit more difficult. But the greatest challenge is to build an application that is actually maintainable for many years (10, 20, 100 years).

Most companies where I worked have a history of rebuilding their applications every 3 to 5 years, some even 2 years. This has extremely high costs, it has a major impact on how successful the application is, and therefore how successful the company is, besides being extremely frustrating for developers to work with a messy code base, and making them want to leave the company. A serious company, with a long-term vision, cannot afford any of it, not the financial loss, not the time loss, not the reputation loss, not the client loss, not the talent loss.

Reflecting the architecture and domain in the codebase is fundamental to the maintainability of an application, and therefore crucial in preventing all those nasty problems.

Explicit Architecture is how I rationalise a set of principles and practices advocated by developers far more experienced than me and how I organise a code base to make it reflect and communicate the architecture and domain of the project.

In my previous post, I talked about how I put all those ideas together and presented some infographics and UMLish diagrams to try to create some kind of a concept map of how I think of it.

However, how do we actually put it to practice in our codebase?!

In this post, I will talk about how I reflect the architecture and the domain of a project in the code and will propose a generic structure that I think that can help us plan for maintainability.

Continue reading “Reflecting architecture and domain in code” →

Action-Domain-Responder

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned about Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

MVC was created in 1979, in a context of desktop applications with CLI user interfaces and it implied that the UI would be changed automatically if there were changes in the database, caused by some factor external to the user. The same pattern was perfectly usable later on desktop applications with a GUI.

However, its usage in web applications has always been an adaptation because most web applications don’t change the UI as a consequence of changes that happen in the server side, there is always a call from the UI asking the server side for an update of the screen.

I have talked about variants of the MVC pattern before, this post is about another variant: Action-Domain-Responder, created by Paul M. Jones. Continue reading “Action-Domain-Responder” →

Resource-Method-Representation

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned about Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

MVC was created in 1979, in a context of desktop applications with CLI user interfaces and it implied that the UI would be changed automatically if there were changes in the database, caused by some factor external to the user. The same pattern was perfectly usable later on desktop applications with a GUI.

However, its usage in web applications has always been an adaptation because most web applications don’t change the UI as a consequence of changes that happen in the server side, there is always a call from the UI asking the server side for an update of the screen.

I have talked about variants of the MVC pattern before, this post is about another variant: Resource-Method-Representation.

I feel the need to talk about it, not because I find it a key pattern in my practice but because of the misconception that it is the same as the ADR pattern, of which I will write about soon. Continue reading “Resource-Method-Representation” →

“Model 1” & “Model 2”

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned about Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

Java Server Pages (JSP) is a technology, a scripting language comparable to PHP, ASP, or even Python, that is used to create server-side pages interpreted by the JVM and which can use Java objects.

The first JSP specifications, published in 1998 by Sun Microsystems, defined two ways of structuring an application so that the presentation logic would be decoupled from the business logic, and even the use cases, in an HTTP request/response paradigm.

Some consider these “Model 1” and “Model 2” the first tries at adapting the MVC pattern, originally intended for a context of desktop software development, to the web HTTP request/response paradigm. Continue reading ““Model 1” & “Model 2”” →

More than concentric layers

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

In my previous post in this series, I published an infographic that reflects the mental map I use to figure out the relationships between the code units types.

However, there was something that I always felt it was not very well reflected there, but I just didn’t know how to do it any better: the shared kernel.

Furthermore, I figured out a few more things, and I’m gonna write about it all in this post!

Continue reading “More than concentric layers” →

DDD, Hexagonal, Onion, Clean, CQRS, … How I put it all together

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned about Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

After graduating from University I followed a career as a high school teacher until a few years ago I decided to drop it and become a full-time software developer.

From then on, I have always felt like I need to recover the “lost” time and learn as much as possible, as fast as possible. So I have become a bit of an addict in experimenting, reading and writing, with a special focus on software design and architecture. That’s why I write these posts, to help me learn.

In my last posts, I’ve been writing about many of the concepts and principles that I’ve learned and a bit about how I reason about them. But I see these as just pieces of big a puzzle.

Today’s post is about how I fit all of these pieces together and, as it seems I should give it a name, I call it Explicit Architecture. Furthermore, these concepts have all “passed their battle trials” and are used in production code on highly demanding platforms. One is a SaaS e-com platform with thousands of web-shops worldwide, another one is a marketplace, live in 2 countries with a message bus that handles over 20 million messages per month.

Continue reading “DDD, Hexagonal, Onion, Clean, CQRS, … How I put it all together” →

Service Oriented Architecture (SOA)

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

The SOA Style has been around since the late 1980s and has its origins in ideas introduced by CORBA, DCOM, DCE and others. Much has been said about SOA, and there are a few different implementation patterns but, in essence, SOA focuses on only a few concepts and doesn’t give any prescription on how to implement them:

  • Composability of user-facing applications;
  • Reusable Business Services;
  • Technology stack independent;
  • Autonomy (independent evolution, scalability & deployability).

SOA is a set of architectural principles independent of any technology or product, just like polymorphism and encapsulation are.

In this post I am going to address the following patterns related to SOA:

Continue reading “Service Oriented Architecture (SOA)” →

From CQS to CQRS

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

When we have an application that is data-centric, ie. implements only basic CRUD operations and leaves the business process (ie. what data to change and in what order) to the user, we have the advantage that the users can change the business process without the need to change the application. In the other hand, this implies that all users need to know all details of all business processes that can be performed using the application, which is a big problem when we have non-trivial processes and a lot of people that need to know them.

In a data-centric application, the application has no knowledge of the business processes, so the domain is unable to have any verbs, and is unable to do anything else aside from changing raw data. It becomes a glorified abstraction of the data model. The processes exist only in the heads of the application users, or even in post-its pinned to the computer screen.

A non-trivial, and really useful, application aims to remove the “process” burden from the user’s shoulders by capturing their intentions, making it an application capable of processing behaviours as opposed to simply storing data.

CQRS is the result of an evolution of several technical concepts that work together to help provide the application with an accurate reflection of the domain, while overcoming common technical limitations. Continue reading “From CQS to CQRS” →

Event-Driven Architecture

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

Using events to design applications is a practice that seems to be around since the late 1980s. We can use events anywhere in the frontend or backend. When a button is pressed, when some data changes or some backend action is performed.

But what is it exactly? When should we use it and how? What are the downsides?

Continue reading “Event-Driven Architecture” →